comisai 1.0.4

package/node_modules/@comis/skills/dist/builtin/platform/discord-action-tool.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Discord action tool: platform-specific actions for Discord servers.
+ *
+ * Supports 19 actions: pin, unpin, kick, ban, unban, role_add, role_remove,
+ * set_topic, set_slowmode, guild_info, channel_info, threadCreate, threadList,
+ * threadReply, channelCreate, channelEdit, channelDelete, channelMove, setPresence.
+ * Destructive actions (kick, ban, channelDelete) require confirmation via action gates.
+ * All actions delegate to the Discord backend via rpcCall("discord.action").
+ *
+ * @module
+ */
+import { Type } from "@sinclair/typebox";
+import { createPlatformActionTool } from "./platform-action-tool.js";
+// ---------------------------------------------------------------------------
+// Parameter schema
+// ---------------------------------------------------------------------------
+const DiscordActionParams = Type.Object({
+    action: Type.Union([
+        Type.Literal("pin"),
+        Type.Literal("unpin"),
+        Type.Literal("kick"),
+        Type.Literal("ban"),
+        Type.Literal("unban"),
+        Type.Literal("role_add"),
+        Type.Literal("role_remove"),
+        Type.Literal("set_topic"),
+        Type.Literal("set_slowmode"),
+        Type.Literal("guild_info"),
+        Type.Literal("channel_info"),
+        Type.Literal("threadCreate"),
+        Type.Literal("threadList"),
+        Type.Literal("threadReply"),
+        Type.Literal("channelCreate"),
+        Type.Literal("channelEdit"),
+        Type.Literal("channelDelete"),
+        Type.Literal("channelMove"),
+        Type.Literal("setPresence"),
+    ], { description: "Discord-specific action. Valid values: pin (pin message), unpin (unpin message), kick (remove member), ban (ban member), unban (unban member), role_add (assign role), role_remove (revoke role), set_topic (change channel topic), set_slowmode (set rate limit), guild_info (get server details), channel_info (get channel details), threadCreate (create thread), threadList (list threads), threadReply (reply in thread), channelCreate (new channel), channelEdit (modify channel), channelDelete (delete channel), channelMove (reorder channel), setPresence (update bot status)" }),
+    channel_id: Type.Optional(Type.String({ description: "Channel ID (for pin/unpin/set_topic/set_slowmode/channel_info/threadCreate/channelEdit/channelDelete/channelMove)" })),
+    guild_id: Type.Optional(Type.String({ description: "Guild/server ID (for kick/ban/unban/role_add/role_remove/guild_info/channelCreate/threadList)" })),
+    user_id: Type.Optional(Type.String({ description: "Target user ID (for kick/ban/unban/role_add/role_remove)" })),
+    message_id: Type.Optional(Type.String({ description: "Message ID (for pin/unpin/threadCreate)" })),
+    role_id: Type.Optional(Type.String({ description: "Role ID (for role_add/role_remove)" })),
+    topic: Type.Optional(Type.String({ description: "Channel topic text (for set_topic)" })),
+    seconds: Type.Optional(Type.Integer({ description: "Slowmode delay in seconds, 0-21600 (for set_slowmode)" })),
+    reason: Type.Optional(Type.String({ description: "Moderation reason (for kick/ban)" })),
+    delete_message_days: Type.Optional(Type.Integer({ description: "Days of messages to delete, 0-7 (for ban)" })),
+    name: Type.Optional(Type.String({ description: "Name for thread or channel (for threadCreate/channelCreate)" })),
+    thread_id: Type.Optional(Type.String({ description: "Thread ID (for threadReply)" })),
+    auto_archive_duration: Type.Optional(Type.Integer({ description: "Thread auto-archive duration in minutes: 60, 1440, 4320, 10080 (for threadCreate)" })),
+    type: Type.Optional(Type.String({ description: "Channel type: text, voice, category, announcement, forum, stage (for channelCreate)" })),
+    parent_id: Type.Optional(Type.String({ description: "Parent category ID (for channelCreate)" })),
+    position: Type.Optional(Type.Integer({ description: "Channel position in the list (for channelMove/channelEdit)" })),
+    status_text: Type.Optional(Type.String({ description: "Bot status text (for setPresence)" })),
+    activity_type: Type.Optional(Type.String({ description: "Bot activity type: playing, watching, listening, competing (for setPresence)" })),
+    _confirmed: Type.Optional(Type.Boolean({
+        description: "Set to true when re-calling a destructive action after user approval. " +
+            "When a gated action returns requiresConfirmation, present the action to the user, " +
+            "and after they approve, call the same action again with _confirmed: true.",
+    })),
+});
+// ---------------------------------------------------------------------------
+// Descriptor + factory wrapper
+// ---------------------------------------------------------------------------
+const discordDescriptor = {
+    name: "discord_action",
+    label: "Discord Actions",
+    description: "Perform Discord-specific actions: pin/unpin messages, kick/ban/unban members, add/remove roles, set channel topic/slowmode, get guild/channel info, create/list/reply to threads, create/edit/delete/move channels, set bot presence. Requires appropriate bot permissions.",
+    parameters: DiscordActionParams,
+    rpcMethod: "discord.action",
+    gatedActions: [
+        { action: "kick", gateKey: "discord.kick", hint: "Ask the user to confirm this kick action, then call again with _confirmed: true." },
+        { action: "ban", gateKey: "discord.ban", hint: "Ask the user to confirm this ban action, then call again with _confirmed: true." },
+        { action: "channelDelete", gateKey: "discord.channelDelete", hint: "Ask the user to confirm this channel deletion, then call again with _confirmed: true." },
+    ],
+};
+/**
+ * Create a Discord action tool with 19 actions.
+ *
+ * Destructive actions (kick, ban, channelDelete) are gated via createActionGate
+ * and return requiresConfirmation:true when the action is classified as destructive.
+ *
+ * @param rpcCall - RPC call function for delegating to the Discord backend
+ * @param logger - Optional structured logger for DEBUG-level operation logging
+ * @returns AgentTool implementing the Discord actions interface
+ */
+export function createDiscordActionTool(rpcCall, logger) {
+    return createPlatformActionTool({ ...discordDescriptor, logger }, rpcCall);
+}

package/node_modules/@comis/skills/dist/builtin/platform/extract-document-tool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Document extraction platform tool: extract text content from document attachments.
+ *
+ * Accepts an attachment URL from the message hint and an optional max_chars
+ * limit. Delegates to the daemon-side media.extract_document rpcCall handler
+ * which resolves the attachment and calls the document extraction pipeline.
+ *
+ * @module
+ */
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { RpcCall } from "./cron-tool.js";
+declare const ExtractDocumentToolParams: import("@sinclair/typebox").TObject<{
+    attachment_url: import("@sinclair/typebox").TString;
+    max_chars: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+/**
+ * Create a document extraction tool that delegates to media.extract_document rpcCall.
+ *
+ * @param rpcCall - RPC function for daemon communication
+ * @returns AgentTool implementing extract_document
+ */
+export declare function createExtractDocumentTool(rpcCall: RpcCall): AgentTool<typeof ExtractDocumentToolParams>;
+export {};

package/node_modules/@comis/skills/dist/builtin/platform/extract-document-tool.js

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Document extraction platform tool: extract text content from document attachments.
+ *
+ * Accepts an attachment URL from the message hint and an optional max_chars
+ * limit. Delegates to the daemon-side media.extract_document rpcCall handler
+ * which resolves the attachment and calls the document extraction pipeline.
+ *
+ * @module
+ */
+import { Type } from "@sinclair/typebox";
+import { jsonResult, readStringParam, readNumberParam } from "./tool-helpers.js";
+// ── Parameter Schema ────────────────────────────────────────────────
+const ExtractDocumentToolParams = Type.Object({
+    attachment_url: Type.String({
+        description: "The attachment URL from the message hint (e.g. tg-file://..., discord://...)",
+    }),
+    max_chars: Type.Optional(Type.Number({
+        description: "Maximum number of characters to extract from the document",
+    })),
+});
+// ── Factory ─────────────────────────────────────────────────────────
+/**
+ * Create a document extraction tool that delegates to media.extract_document rpcCall.
+ *
+ * @param rpcCall - RPC function for daemon communication
+ * @returns AgentTool implementing extract_document
+ */
+export function createExtractDocumentTool(rpcCall) {
+    return {
+        name: "extract_document",
+        label: "Document Extraction",
+        description: "Extract text content from a document attachment (PDF, CSV, TXT, etc.). Pass the attachment_url from the message hint. Optionally limit extracted characters with max_chars.",
+        parameters: ExtractDocumentToolParams,
+        async execute(_toolCallId, params) {
+            try {
+                const p = params;
+                const attachmentUrl = readStringParam(p, "attachment_url");
+                const maxChars = readNumberParam(p, "max_chars", false);
+                const result = await rpcCall("media.extract_document", {
+                    attachment_url: attachmentUrl,
+                    max_chars: maxChars,
+                });
+                return jsonResult(result);
+            }
+            catch (err) {
+                if (err instanceof Error && err.message.startsWith("["))
+                    throw err;
+                throw err instanceof Error ? err : new Error(String(err));
+            }
+        },
+    };
+}

package/node_modules/@comis/skills/dist/builtin/platform/fts5-sanitizer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * FTS5 query sanitization utility.
+ *
+ * Sanitization logic to protect against FTS5
+ * query injection and handle edge cases with special characters, boolean
+ * operators, dotted terms, and hyphenated terms.
+ *
+ * @module
+ */
+/**
+ * Sanitize a raw user query string for safe use in FTS5 substring matching.
+ *
+ * Steps (order matters):
+ * 1. Protect balanced quoted phrases (extract and replace with placeholders)
+ * 2. Strip unmatched FTS5-special characters: + { } ( ) \ " ^
+ * 3. Collapse repeated * to single *; remove leading *
+ * 4. Remove dangling boolean operators (AND/OR/NOT at start/end)
+ * 5. Wrap dotted terms (e.g., P2.2) and hyphenated terms (e.g., chat-send) in double quotes
+ * 6. Restore balanced quoted phrases from placeholders
+ * 7. Trim and collapse whitespace
+ *
+ * If the result is empty after sanitization, returns the original input trimmed.
+ *
+ * @param raw - The raw user query string
+ * @returns The sanitized query string safe for FTS5
+ */
+export declare function sanitizeFts5Query(raw: string): string;

package/node_modules/@comis/skills/dist/builtin/platform/fts5-sanitizer.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * FTS5 query sanitization utility.
+ *
+ * Sanitization logic to protect against FTS5
+ * query injection and handle edge cases with special characters, boolean
+ * operators, dotted terms, and hyphenated terms.
+ *
+ * @module
+ */
+/**
+ * Sanitize a raw user query string for safe use in FTS5 substring matching.
+ *
+ * Steps (order matters):
+ * 1. Protect balanced quoted phrases (extract and replace with placeholders)
+ * 2. Strip unmatched FTS5-special characters: + { } ( ) \ " ^
+ * 3. Collapse repeated * to single *; remove leading *
+ * 4. Remove dangling boolean operators (AND/OR/NOT at start/end)
+ * 5. Wrap dotted terms (e.g., P2.2) and hyphenated terms (e.g., chat-send) in double quotes
+ * 6. Restore balanced quoted phrases from placeholders
+ * 7. Trim and collapse whitespace
+ *
+ * If the result is empty after sanitization, returns the original input trimmed.
+ *
+ * @param raw - The raw user query string
+ * @returns The sanitized query string safe for FTS5
+ */
+export function sanitizeFts5Query(raw) {
+    if (!raw || !raw.trim())
+        return raw?.trim() ?? "";
+    const trimmed = raw.trim();
+    // Step 1: Protect balanced quoted phrases
+    const quotedPhrases = [];
+    let working = trimmed.replace(/"([^"]+)"/g, (_match, phrase) => {
+        const idx = quotedPhrases.length;
+        quotedPhrases.push(`"${phrase}"`);
+        return `__QUOTED_${idx}__`;
+    });
+    // Step 2: Strip unmatched FTS5-special characters: + { } ( ) \ " ^
+    working = working.replace(/[+{}()\\"^]/g, "");
+    // Step 3: Collapse repeated * to single *; remove leading *
+    working = working.replace(/\*{2,}/g, "*");
+    working = working.replace(/^\*/, "");
+    // Also remove leading * after whitespace (per-token leading stars)
+    working = working.replace(/(\s)\*/g, "$1");
+    // Step 4: Remove dangling boolean operators at start/end
+    // Remove operators at the start
+    working = working.replace(/^\s*\b(AND|OR|NOT)\b\s*/i, "");
+    // Remove operators at the end
+    working = working.replace(/\s*\b(AND|OR|NOT)\b\s*$/i, "");
+    // Remove isolated dangling operators that would create invalid expressions
+    // e.g., "query AND" or "AND query" already handled above
+    // Also handle "query AND OR other" -> "query other"
+    working = working.replace(/\b(AND|OR|NOT)\s+(AND|OR|NOT)\b/gi, "");
+    // Step 5: Wrap dotted terms and hyphenated terms in double quotes
+    // Split into tokens, wrap any token containing . or - between word chars
+    working = working.split(/\s+/).map((token) => {
+        if (token.startsWith("__QUOTED_"))
+            return token;
+        // Dotted terms: P2.2, v1.0.3 (word chars joined by dots, at least one dot)
+        if (/^\w+\.\w[\w.]*$/.test(token))
+            return `"${token}"`;
+        // Hyphenated terms: chat-send, foo-bar-baz (word chars joined by hyphens)
+        if (/^\w+-\w[\w-]*$/.test(token))
+            return `"${token}"`;
+        return token;
+    }).join(" ");
+    // Step 6: Restore balanced quoted phrases from placeholders
+    for (let i = 0; i < quotedPhrases.length; i++) {
+        working = working.replace(`__QUOTED_${i}__`, quotedPhrases[i]);
+    }
+    // Step 7: Trim and collapse whitespace
+    working = working.replace(/\s+/g, " ").trim();
+    // If result is empty after sanitization, return original trimmed
+    if (!working)
+        return trimmed;
+    return working;
+}

package/node_modules/@comis/skills/dist/builtin/platform/gateway-tool.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Gateway control tool: multi-action tool for infrastructure management.
+ *
+ * Supports 11 actions: read, patch, apply, restart, schema, status, history, diff, rollback, env_set, env_list.
+ * Destructive actions (restart, rollback, apply, env_set) and mutation action (patch) require
+ * confirmation via action gates. Read-only actions (read, schema, status, history, diff, env_list)
+ * are unconfirmed. All actions delegate to the daemon backend via rpcCall.
+ *
+ * @module
+ */
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { RpcCall } from "./cron-tool.js";
+/**
+ * Canonical list of gateway tool actions. Single source of truth --
+ * the Typebox `action` Union below and the bridge's pre-flight
+ * validator in `packages/skills/src/bridge/tool-metadata-registry.ts`
+ * both derive from this tuple. Adding a new action here automatically
+ * updates both the schema and the bridge whitelist, eliminating the
+ * dual-source-of-truth drift that caused the `env_list`-rejected bug.
+ */
+export declare const GATEWAY_ACTIONS: readonly ["read", "patch", "apply", "restart", "schema", "status", "history", "diff", "rollback", "env_set", "env_list"];
+export type GatewayAction = typeof GATEWAY_ACTIONS[number];
+declare const GatewayToolParams: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"status" | "read" | "patch" | "diff" | "apply" | "restart" | "schema" | "history" | "rollback" | "env_set" | "env_list">[]>;
+    section: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    key: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    sha: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    env_key: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    env_value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    filter: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    _confirmed: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
+/**
+ * Create a gateway control tool with 11 actions.
+ *
+ * Actions:
+ * - **read** -- Read current config for a section (or all sections)
+ * - **patch** -- Update a config key within a section (gated, immutable keys rejected)
+ * - **apply** -- Replace an entire config section atomically (gated as destructive, triggers restart)
+ * - **restart** -- Restart the gateway server (gated as destructive)
+ * - **schema** -- Get JSON Schema for a section (or full config) for introspection
+ * - **status** -- Get current gateway server status (uptime, connections, etc.)
+ * - **history** -- View config change history with optional section filter and limit
+ * - **diff** -- View unified diff of config changes against a previous version
+ * - **rollback** -- Restore config to a previous version (gated as destructive, triggers restart)
+ * - **env_set** -- Store a secret/env var (write-only, requires confirmation, triggers restart)
+ * - **env_list** -- List configured secret NAMES (admin-only, read-only). Use before asking the user for a key to check whether it is already configured. Values are never returned.
+ *
+ * @param rpcCall - RPC call function for delegating to the daemon backend
+ * @returns AgentTool implementing the gateway control interface
+ */
+export declare function createGatewayTool(rpcCall: RpcCall): AgentTool<typeof GatewayToolParams>;
+export {};

package/node_modules/@comis/skills/dist/builtin/platform/gateway-tool.js

@@ -0,0 +1,255 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Gateway control tool: multi-action tool for infrastructure management.
+ *
+ * Supports 11 actions: read, patch, apply, restart, schema, status, history, diff, rollback, env_set, env_list.
+ * Destructive actions (restart, rollback, apply, env_set) and mutation action (patch) require
+ * confirmation via action gates. Read-only actions (read, schema, status, history, diff, env_list)
+ * are unconfirmed. All actions delegate to the daemon backend via rpcCall.
+ *
+ * @module
+ */
+import { Type } from "@sinclair/typebox";
+import { tryGetContext, isImmutableConfigPath, MUTABLE_CONFIG_OVERRIDES, matchesOverridePattern, getMutableOverridesForSection } from "@comis/core";
+import { readStringParam, throwToolError, createActionGate, } from "./tool-helpers.js";
+import { createMultiActionDispatchTool } from "./messaging-factory.js";
+// ---------------------------------------------------------------------------
+// Canonical action list -- single source of truth
+// ---------------------------------------------------------------------------
+/**
+ * Canonical list of gateway tool actions. Single source of truth --
+ * the Typebox `action` Union below and the bridge's pre-flight
+ * validator in `packages/skills/src/bridge/tool-metadata-registry.ts`
+ * both derive from this tuple. Adding a new action here automatically
+ * updates both the schema and the bridge whitelist, eliminating the
+ * dual-source-of-truth drift that caused the `env_list`-rejected bug.
+ */
+export const GATEWAY_ACTIONS = [
+    "read",
+    "patch",
+    "apply",
+    "restart",
+    "schema",
+    "status",
+    "history",
+    "diff",
+    "rollback",
+    "env_set",
+    "env_list",
+];
+// ---------------------------------------------------------------------------
+// Parameter schema
+// ---------------------------------------------------------------------------
+const GatewayToolParams = Type.Object({
+    action: Type.Union(GATEWAY_ACTIONS.map((a) => Type.Literal(a)), { description: "Gateway control action. Valid values: read (view config section), patch (update single config key), apply (replace entire section), restart (restart gateway), schema (get JSON schema), status (server uptime/connections), history (config change log), diff (compare config versions), rollback (restore previous config), env_set (store secret), env_list (list configured secret names -- read-only, never returns values)" }),
+    section: Type.Optional(Type.String({
+        description: "Config section name. Required for patch/apply/schema, optional for read. " +
+            "Valid sections: agents, channels, memory, security, routing, daemon, scheduler, " +
+            "gateway, integrations, monitoring, browser, models, providers, messages, approvals. " +
+            "Note: MCP server settings are under 'integrations', not 'mcp'.",
+    })),
+    key: Type.Optional(Type.String({
+        description: "Dot-notation key within section for patch. For agents section, prefix with the agent ID (e.g., default.model, default.provider, default.maxSteps). Use 'read' action first to see current keys and agent IDs.",
+    })),
+    value: Type.Optional(Type.Unknown({
+        description: "New value for patch (string, number, boolean, object, or array)",
+    })),
+    limit: Type.Optional(Type.Number({
+        description: "Maximum results. For history: default 10. For env_list: default 100, max 500 (clamped).",
+    })),
+    sha: Type.Optional(Type.String({
+        description: "Git commit SHA for diff comparison or rollback target",
+    })),
+    env_key: Type.Optional(Type.String({
+        description: "Environment variable / secret name (uppercase, e.g., OPENAI_API_KEY). Required for env_set. " +
+            "After storing a secret via env_set, reference it in config YAML as ${VAR_NAME} " +
+            "(e.g., GEMINI_API_KEY: ${GEMINI_API_KEY}). Never write raw API keys into config.",
+    })),
+    env_value: Type.Optional(Type.String({
+        description: "Secret value to store. Required for env_set. Write-only: cannot be read back.",
+    })),
+    filter: Type.Optional(Type.String({
+        description: "Glob filter for env_list (e.g., 'GEMINI*', '*_API_KEY'). Case-insensitive, " +
+            "supports '*' wildcard. Matches only secret NAMES -- values are never returned.",
+    })),
+    _confirmed: Type.Optional(Type.Boolean({
+        description: "Set to true when re-calling a destructive action after user approval. " +
+            "When a gated action returns requiresConfirmation, present the action to the user, " +
+            "and after they approve, call the same action again with _confirmed: true.",
+    })),
+});
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a gateway control tool with 11 actions.
+ *
+ * Actions:
+ * - **read** -- Read current config for a section (or all sections)
+ * - **patch** -- Update a config key within a section (gated, immutable keys rejected)
+ * - **apply** -- Replace an entire config section atomically (gated as destructive, triggers restart)
+ * - **restart** -- Restart the gateway server (gated as destructive)
+ * - **schema** -- Get JSON Schema for a section (or full config) for introspection
+ * - **status** -- Get current gateway server status (uptime, connections, etc.)
+ * - **history** -- View config change history with optional section filter and limit
+ * - **diff** -- View unified diff of config changes against a previous version
+ * - **rollback** -- Restore config to a previous version (gated as destructive, triggers restart)
+ * - **env_set** -- Store a secret/env var (write-only, requires confirmation, triggers restart)
+ * - **env_list** -- List configured secret NAMES (admin-only, read-only). Use before asking the user for a key to check whether it is already configured. Values are never returned.
+ *
+ * @param rpcCall - RPC call function for delegating to the daemon backend
+ * @returns AgentTool implementing the gateway control interface
+ */
+export function createGatewayTool(rpcCall) {
+    const restartGate = createActionGate("gateway.restart");
+    const patchGate = createActionGate("config.patch");
+    const applyGate = createActionGate("config.apply");
+    const rollbackGate = createActionGate("config.rollback");
+    const envSetGate = createActionGate("env.set");
+    return createMultiActionDispatchTool({
+        name: "gateway",
+        label: "Gateway Control",
+        description: "Read/patch config, restart gateway, check status. Destructive actions require confirmation.",
+        parameters: GatewayToolParams,
+        validActions: GATEWAY_ACTIONS,
+        actionHandler: async (action, p, rpcCall) => {
+            const ctx = tryGetContext();
+            const _trustLevel = ctx?.trustLevel ?? "guest";
+            switch (action) {
+                case "read": {
+                    const section = readStringParam(p, "section", false);
+                    return rpcCall("config.read", { section, _trustLevel });
+                }
+                case "patch": {
+                    const section = readStringParam(p, "section");
+                    const key = readStringParam(p, "key");
+                    // Pre-gate immutability check: reject before asking for confirmation
+                    if (isImmutableConfigPath(section, key)) {
+                        const mutablePaths = getMutableOverridesForSection(section, key);
+                        let hint;
+                        if (mutablePaths.length > 0) {
+                            hint = `Patchable paths under "${section}": ${mutablePaths.join(", ")}`;
+                        }
+                        else if (section === "agents") {
+                            hint = `Key must start with the agent ID. Use action="read" section="agents" first to see agent IDs, then patch as e.g. key="<agentId>.model"`;
+                        }
+                        else {
+                            hint = "This section has no runtime-patchable paths.";
+                        }
+                        throwToolError("permission_denied", `Cannot patch immutable config path: ${section}.${key}.`, { hint });
+                    }
+                    // Skip confirmation gate for known mutable override paths (no round-trip needed)
+                    const fullPath = key ? `${section}.${key}` : section;
+                    const isMutableOverride = MUTABLE_CONFIG_OVERRIDES.some(pattern => matchesOverridePattern(fullPath, pattern));
+                    if (!isMutableOverride) {
+                        const gate = patchGate(p);
+                        if (gate.requiresConfirmation) {
+                            return {
+                                requiresConfirmation: true,
+                                actionType: gate.actionType,
+                                hint: "Ask the user to confirm this config patch, then call again with _confirmed: true.",
+                            };
+                        }
+                    }
+                    const value = p.value;
+                    return rpcCall("config.patch", { section, key, value, _trustLevel });
+                }
+                case "restart": {
+                    const gate = restartGate(p);
+                    if (gate.requiresConfirmation) {
+                        return {
+                            requiresConfirmation: true,
+                            actionType: gate.actionType,
+                            hint: "Ask the user to confirm this restart, then call again with _confirmed: true.",
+                        };
+                    }
+                    return rpcCall("gateway.restart", { _trustLevel });
+                }
+                case "schema": {
+                    const section = readStringParam(p, "section", false);
+                    return rpcCall("config.schema", { section, _trustLevel });
+                }
+                case "status": {
+                    return rpcCall("gateway.status", { _trustLevel });
+                }
+                case "history": {
+                    const section = readStringParam(p, "section", false);
+                    const limit = p.limit;
+                    return rpcCall("config.history", { section, limit, _trustLevel });
+                }
+                case "diff": {
+                    const sha = readStringParam(p, "sha", false);
+                    return rpcCall("config.diff", { sha, _trustLevel });
+                }
+                case "apply": {
+                    const section = readStringParam(p, "section");
+                    // Pre-gate immutability check: reject before asking for confirmation
+                    if (isImmutableConfigPath(section)) {
+                        throwToolError("permission_denied", `Cannot apply to immutable config section: ${section}.`, { hint: "Security-sensitive sections cannot be replaced at runtime." });
+                    }
+                    const gate = applyGate(p);
+                    if (gate.requiresConfirmation) {
+                        return {
+                            requiresConfirmation: true,
+                            actionType: gate.actionType,
+                            hint: "Ask the user to confirm this config apply, then call again with _confirmed: true.",
+                        };
+                    }
+                    const value = p.value;
+                    return rpcCall("config.apply", { section, value, _trustLevel });
+                }
+                case "rollback": {
+                    const gate = rollbackGate(p);
+                    if (gate.requiresConfirmation) {
+                        return {
+                            requiresConfirmation: true,
+                            actionType: gate.actionType,
+                            hint: "Ask the user to confirm this rollback, then call again with _confirmed: true.",
+                        };
+                    }
+                    const sha = readStringParam(p, "sha");
+                    return rpcCall("config.rollback", { sha, _trustLevel });
+                }
+                case "env_list": {
+                    // Read-only: no confirmation gate. Names only; values are never returned.
+                    const filter = readStringParam(p, "filter", false);
+                    const limit = typeof p.limit === "number" ? p.limit : undefined;
+                    return rpcCall("env.list", { filter, limit, _trustLevel });
+                }
+                default: {
+                    // action === "env_set"
+                    const envKey = readStringParam(p, "env_key");
+                    const envValue = readStringParam(p, "env_value");
+                    // Reject session-redaction placeholders. This catches the replay
+                    // poisoning loop where a prior env_set tool call's arguments were
+                    // rewritten to "[REDACTED]" on disk by sanitizeSessionSecrets,
+                    // then replayed back into the model's context, causing it to
+                    // emit "[REDACTED]" as the value on the next env_set.
+                    // scrubRedactedToolCalls handles this upstream; this is the
+                    // last line of defense at the tool boundary.
+                    if (envValue === "[REDACTED]" || /^\[REDACTED[^\]]*\]$/.test(envValue)) {
+                        return {
+                            error: "env_value_is_placeholder",
+                            hint: `env_value "${envValue}" is a session-redaction placeholder, ` +
+                                `not a real secret. Re-read the user's most recent message ` +
+                                `and call env_set again with the literal value they provided.`,
+                        };
+                    }
+                    const gate = envSetGate(p);
+                    if (gate.requiresConfirmation) {
+                        return {
+                            requiresConfirmation: true,
+                            actionType: gate.actionType,
+                            hint: `Confirm setting secret "${envKey}". Call again with _confirmed: true.`,
+                        };
+                    }
+                    const result = await rpcCall("env.set", { key: envKey, value: envValue, _trustLevel });
+                    // Return result but strip any value that might have leaked through
+                    return typeof result === "object" && result !== null
+                        ? { ...result, value: undefined }
+                        : result;
+                }
+            }
+        },
+    }, rpcCall);
+}

package/node_modules/@comis/skills/dist/builtin/platform/heartbeat-manage-tool.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Heartbeat management tool: multi-action tool for heartbeat configuration.
+ *
+ * Supports 4 actions: get, update, status, trigger.
+ * All actions enforce admin trust level via createTrustGuard.
+ * Delegates to heartbeat.* RPC handlers via rpcCall.
+ *
+ * @module
+ */
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { RpcCall } from "./cron-tool.js";
+declare const HeartbeatManageToolParams: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"get">, import("@sinclair/typebox").TLiteral<"update">, import("@sinclair/typebox").TLiteral<"status">, import("@sinclair/typebox").TLiteral<"trigger">]>;
+    agent_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    enabled: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    interval_ms: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    prompt: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    target_channel_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    target_channel_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    target_chat_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    target_is_dm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    light_context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    show_ok: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    show_alerts: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    allow_dm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    skip_heartbeat_only_delivery: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    ack_max_chars: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    response_prefix: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    session: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    alert_threshold: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    alert_cooldown_ms: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    stale_ms: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+}>;
+export declare function createHeartbeatManageTool(rpcCall: RpcCall): AgentTool<typeof HeartbeatManageToolParams>;
+export {};