@ouro.bot/cli 0.1.0-alpha.8 → 0.1.0-alpha.800

package/dist/repertoire/tools-surface.js

@@ -0,0 +1,369 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.surfaceToolDefinition = exports.surfaceToolDef = void 0;
+const fs = __importStar(require("fs"));
+const crypto_1 = require("crypto");
+const config_1 = require("../heart/config");
+const identity_1 = require("../heart/identity");
+const surface_tool_1 = require("../senses/surface-tool");
+const obligations_1 = require("../arc/obligations");
+const packets_1 = require("../arc/packets");
+const session_activity_1 = require("../heart/session-activity");
+const bluebubbles_meta_guard_1 = require("../senses/bluebubbles-meta-guard");
+const runtime_1 = require("../nerves/runtime");
+const path = __importStar(require("path"));
+const outbound_1 = require("../senses/voice/outbound");
+/* v8 ignore start -- surface voice delivery hints are covered at the outbound voice bridge; this adapter only normalizes optional tool args @preserve */
+function normalizeSurfaceDeliveryChannel(value) {
+    if (typeof value !== "string")
+        return "auto";
+    const normalized = value.trim().toLowerCase();
+    return normalized === "voice" ? "voice" : "auto";
+}
+function parseSurfaceVoiceInitialAudio(args) {
+    const source = args.voiceAudioSource === "url" || args.voiceAudioSource === "file" || args.voiceAudioSource === "tone"
+        ? args.voiceAudioSource
+        : undefined;
+    const hasAudioHint = Boolean(source
+        || args.voiceAudioUrl?.trim()
+        || args.voiceAudioPath?.trim()
+        || args.voiceAudioLabel?.trim()
+        || args.voiceAudioToneHz?.trim()
+        || args.voiceAudioDurationMs?.trim());
+    if (!hasAudioHint)
+        return undefined;
+    const toneHz = args.voiceAudioToneHz?.trim() ? Number(args.voiceAudioToneHz) : undefined;
+    const durationMs = args.voiceAudioDurationMs?.trim() ? Number(args.voiceAudioDurationMs) : undefined;
+    return {
+        source: source ?? "tone",
+        ...(args.voiceAudioUrl?.trim() ? { url: args.voiceAudioUrl.trim() } : {}),
+        ...(args.voiceAudioPath?.trim() ? { path: args.voiceAudioPath.trim() } : {}),
+        ...(args.voiceAudioLabel?.trim() ? { label: args.voiceAudioLabel.trim() } : {}),
+        ...(Number.isFinite(toneHz) ? { toneHz } : {}),
+        ...(Number.isFinite(durationMs) ? { durationMs } : {}),
+    };
+}
+/* v8 ignore stop */
+// Surface tool schema — canonical home. Handler lives in senses/surface-tool.ts.
+exports.surfaceToolDef = {
+    type: "function",
+    function: {
+        name: "surface",
+        description: "return a ready thought to a friend or active session without publishing private-runtime work to BlueBubbles. pass delegationId to address a held thought (see your attention queue above), or friendId for spontaneous outreach. Surface delivers tool responses to the active session. BlueBubbles is a dedicated channel - use send_message with channel=\"bluebubbles\" for intentional iMessage delivery. set channel=voice only when you intentionally want a live phone call; content becomes the call reason/opening context. does not end your turn.",
+        parameters: {
+            type: "object",
+            properties: {
+                content: {
+                    type: "string",
+                    description: "the message to deliver",
+                },
+                delegationId: {
+                    type: "string",
+                    description: "ID from your attention queue — addresses a specific held thought",
+                },
+                friendId: {
+                    type: "string",
+                    description: "friend to reach out to spontaneously (when not addressing a held thought)",
+                },
+                channel: {
+                    type: "string",
+                    enum: ["auto", "voice"],
+                    description: "optional delivery channel; use voice for a live phone call to a trusted friend, otherwise omit",
+                },
+                phoneNumber: {
+                    type: "string",
+                    description: "optional E.164 phone override for channel=voice when the trusted friend's record has no usable phone handle",
+                },
+                voiceAudioSource: {
+                    type: "string",
+                    enum: ["tone", "url", "file"],
+                    description: "optional initial non-speech audio to play after the opening greeting when channel=voice",
+                },
+                voiceAudioUrl: {
+                    type: "string",
+                    description: "short audio URL for voiceAudioSource=url",
+                },
+                voiceAudioPath: {
+                    type: "string",
+                    description: "local audio file path for voiceAudioSource=file",
+                },
+                voiceAudioLabel: {
+                    type: "string",
+                    description: "short label for the initial voice audio",
+                },
+                voiceAudioToneHz: {
+                    type: "number",
+                    description: "tone frequency for voiceAudioSource=tone",
+                },
+                voiceAudioDurationMs: {
+                    type: "number",
+                    description: "initial audio duration in milliseconds",
+                },
+            },
+            required: ["content"],
+        },
+    },
+};
+// Surface tool handler: routes content to friend's freshest session
+/* v8 ignore start -- surface handler wiring: core logic tested via surface-tool.test.ts; this wires identity/routing deps @preserve */
+exports.surfaceToolDefinition = {
+    tool: exports.surfaceToolDef,
+    handler: async (args, ctx) => {
+        const rawContent = args.content ?? "";
+        const deliveryHint = {
+            channel: normalizeSurfaceDeliveryChannel(args.channel),
+            phoneNumber: typeof args.phoneNumber === "string" ? args.phoneNumber : undefined,
+            initialAudio: parseSurfaceVoiceInitialAudio(args),
+        };
+        if ((0, bluebubbles_meta_guard_1.containsInternalMetaMarkers)(rawContent)) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "repertoire",
+                event: "tools.surface_meta_blocked",
+                message: "surface tool blocked: internal meta markers in content",
+                meta: {
+                    hasDelegationId: Boolean(args.delegationId),
+                    hasFriendId: Boolean(args.friendId),
+                    contentLength: rawContent.length,
+                },
+            });
+            return "failed — blocked: contains internal meta markers";
+        }
+        const queue = ctx?.delegatedOrigins ?? [];
+        const agentName = (() => { try {
+            return (0, identity_1.getAgentName)();
+        }
+        catch {
+            return "unknown";
+        } })();
+        const routeToFriend = async (friendId, content, queueItem, hint) => {
+            /* v8 ignore start -- routing: integration path tested via private-runtime routing tests @preserve */
+            try {
+                const agentRoot = (0, identity_1.getAgentRoot)();
+                const sessionsDir = path.join(agentRoot, "state", "sessions");
+                const friendsDir = path.join(agentRoot, "friends");
+                const queueToSession = async (target, detail) => {
+                    const { queuePendingMessage, getPendingDir } = await Promise.resolve().then(() => __importStar(require("../mind/pending")));
+                    const pendingDir = getPendingDir(agentName, target.friendId, target.channel, target.key);
+                    queuePendingMessage(pendingDir, {
+                        from: agentName,
+                        friendId: target.friendId,
+                        channel: target.channel,
+                        key: target.key,
+                        content,
+                        timestamp: Date.now(),
+                    });
+                    return { status: "queued", detail };
+                };
+                const deliverTelegramOrQueue = async (target, detail) => {
+                    const telegramKey = (0, config_1.canonicalizeTelegramSessionKey)(target.key);
+                    const hash = (0, crypto_1.createHash)("sha256").update(`${target.friendId}\0${telegramKey}\0${content}`).digest("hex");
+                    const requestId = queueItem?.obligationId ?? `surface:${hash}`;
+                    const deliveryId = queueItem?.obligationId ? `surface:${queueItem.obligationId}:${hash}` : `surface:${hash}`;
+                    const { sendTelegramAwaitFollowUp } = await Promise.resolve().then(() => __importStar(require("../senses/telegram")));
+                    const delivered = await sendTelegramAwaitFollowUp(agentName, {
+                        friendId: target.friendId,
+                        channel: "telegram",
+                        key: telegramKey,
+                        content,
+                        requestId,
+                        deliveryId,
+                        intent: "generic_outreach",
+                    });
+                    return delivered.status === "delivered_now"
+                        ? { status: "delivered", detail: "sent to Telegram now" }
+                        : queueToSession(target, detail);
+                };
+                // Resolve friend name → UUID if needed (agents may pass name instead of UUID)
+                let resolvedFriendId = friendId;
+                if (!fs.existsSync(path.join(sessionsDir, friendId))) {
+                    try {
+                        const friendFiles = fs.readdirSync(friendsDir).filter((f) => f.endsWith(".json"));
+                        for (const file of friendFiles) {
+                            const raw = fs.readFileSync(path.join(friendsDir, file), "utf-8");
+                            const record = JSON.parse(raw);
+                            if (record.name?.toLowerCase() === friendId.toLowerCase() && record.id) {
+                                resolvedFriendId = record.id;
+                                break;
+                            }
+                        }
+                    }
+                    catch { /* friends dir unreadable — continue with original friendId */ }
+                }
+                friendId = resolvedFriendId;
+                if (hint?.channel === "voice") {
+                    const voiceResult = await (0, outbound_1.placeTrustedFriendVoiceOutboundCall)({
+                        agentName,
+                        agentRoot,
+                        friendId,
+                        reason: content,
+                        phoneNumber: hint.phoneNumber,
+                        ...(hint.initialAudio ? { initialAudio: hint.initialAudio } : {}),
+                    });
+                    return voiceResult.status === "placed"
+                        ? { status: "delivered", detail: voiceResult.detail }
+                        : { status: "failed", detail: voiceResult.detail };
+                }
+                // Priority 1: Bridge-preferred session (if queue item has a bridgeId)
+                if (queueItem?.bridgeId) {
+                    const { createBridgeManager } = await Promise.resolve().then(() => __importStar(require("../heart/bridges/manager")));
+                    const bridge = createBridgeManager().getBridge(queueItem.bridgeId);
+                    if (bridge && bridge.lifecycle !== "completed" && bridge.lifecycle !== "cancelled") {
+                        const allSessions = (0, session_activity_1.listSessionActivity)({ sessionsDir, friendsDir, agentName, activeThresholdMs: Number.MAX_SAFE_INTEGER });
+                        const bridgeTarget = allSessions.find((activity) => activity.friendId === friendId
+                            && activity.channel !== "inner"
+                            && bridge.attachedSessions.some((s) => s.friendId === activity.friendId && s.channel === activity.channel && s.key === activity.key));
+                        if (bridgeTarget) {
+                            const detail = `for next interaction via ${bridgeTarget.channel}`;
+                            return bridgeTarget.channel === "telegram"
+                                ? deliverTelegramOrQueue(bridgeTarget, detail)
+                                : queueToSession(bridgeTarget, detail);
+                        }
+                    }
+                }
+                // Priority 1.5: exact held-work origin.
+                // A delegated return has a concrete reply address. Preserve that
+                // address before considering fresher sessions for the same friend,
+                // especially MCP sessions where check_response drains this path.
+                if (queueItem?.channel && queueItem.key && queueItem.channel !== "inner") {
+                    const target = { friendId, channel: queueItem.channel, key: queueItem.key };
+                    const detail = `for originating ${queueItem.channel} session`;
+                    return queueItem.channel === "telegram"
+                        ? deliverTelegramOrQueue(target, detail)
+                        : queueToSession(target, detail);
+                }
+                // Priority 2: Try proactive delivery first, then queue to freshest session
+                const allFriendSessions = (0, session_activity_1.listSessionActivity)({ sessionsDir, friendsDir, agentName, activeThresholdMs: Number.MAX_SAFE_INTEGER })
+                    .filter((s) => s.friendId === friendId && s.channel !== "inner");
+                // Priority 2: Queue to freshest non-private-runtime session
+                const freshest = allFriendSessions[0];
+                if (freshest) {
+                    const detail = `for next interaction via ${freshest.channel}`;
+                    return freshest.channel === "telegram"
+                        ? deliverTelegramOrQueue(freshest, detail)
+                        : queueToSession(freshest, detail);
+                }
+                // Priority 3: Deferred — no active session found
+                const { getDeferredReturnDir } = await Promise.resolve().then(() => __importStar(require("../mind/pending")));
+                const { queuePendingMessage: queueDeferred } = await Promise.resolve().then(() => __importStar(require("../mind/pending")));
+                const deferredDir = getDeferredReturnDir(agentName, friendId);
+                queueDeferred(deferredDir, {
+                    from: agentName,
+                    friendId,
+                    channel: "deferred",
+                    key: "return",
+                    content,
+                    timestamp: Date.now(),
+                });
+                return { status: "deferred", detail: "they'll see it next time" };
+            }
+            catch {
+                return { status: "failed" };
+            }
+            /* v8 ignore stop */
+        };
+        return (0, surface_tool_1.handleSurface)({
+            content: args.content ?? "",
+            delegationId: args.delegationId,
+            friendId: args.friendId,
+            deliveryHint: deliveryHint.channel === "voice" || deliveryHint.phoneNumber ? deliveryHint : undefined,
+            queue,
+            routeToFriend,
+            advanceObligation: (obligationId, update) => {
+                /* v8 ignore start -- obligation advance: tested via attention-queue tests @preserve */
+                try {
+                    const name = (() => { try {
+                        return (0, identity_1.getAgentName)();
+                    }
+                    catch {
+                        return "unknown";
+                    } })();
+                    (0, obligations_1.advanceReturnObligation)(name, obligationId, {
+                        status: update.status,
+                        ...(update.returnedAt !== undefined ? { returnedAt: update.returnedAt } : {}),
+                        ...(update.returnTarget !== undefined ? { returnTarget: update.returnTarget } : {}),
+                    });
+                }
+                catch {
+                    // swallowed — obligation advance must never break surface delivery
+                }
+                /* v8 ignore stop */
+            },
+            completePonderPacket: (packetId) => {
+                /* v8 ignore start -- packet completion: tested via surface-tool and arc packet unit tests @preserve */
+                try {
+                    (0, packets_1.completePonderPacket)((0, identity_1.getAgentRoot)(), packetId);
+                }
+                catch {
+                    // swallowed — packet completion must never break surface delivery
+                }
+                /* v8 ignore stop */
+            },
+            fulfillHeartObligation: (origin) => {
+                /* v8 ignore start -- heart obligation fulfillment: tested via surface-tool.test.ts @preserve */
+                try {
+                    const agentRoot = (0, identity_1.getAgentRoot)();
+                    const heartObligation = (0, obligations_1.findPendingObligationForOrigin)(agentRoot, origin);
+                    if (heartObligation) {
+                        (0, obligations_1.fulfillObligation)(agentRoot, heartObligation.id);
+                    }
+                }
+                catch {
+                    // swallowed — heart obligation fulfillment must never break surface delivery
+                }
+                /* v8 ignore stop */
+            },
+            onRouteResult: ({ targetFriendId, queueItem, result }) => {
+                ctx?.habitSession?.recordSurfaceAttempt?.({
+                    recipient: targetFriendId,
+                    channel: queueItem?.channel ?? args.channel ?? "surface",
+                    reason: result.status === "failed" ? "blocked" : "answer",
+                    result: result.status,
+                    rawStatus: result.status,
+                    ...(queueItem ? { routeKind: "originator" } : {}),
+                    ...(result.status === "failed" ? { error: result.detail ?? "surface route failed" } : {}),
+                });
+            },
+        });
+    },
+    summaryKeys: ["content", "delegationId", "friendId", "channel"],
+    riskProfile: {
+        mutates: ["durable_state_write", "external_side_effect"],
+        risk: "high",
+        reason: "queues or delivers surfaced responses and may fulfill obligations",
+    },
+};
+/* v8 ignore stop */

package/dist/repertoire/tools-teams.js

@@ -3,24 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.teamsToolHandlers = exports.teamsTools = exports.teamsToolDefinitions = void 0;
-exports.summarizeTeamsArgs = summarizeTeamsArgs;
+exports.teamsToolDefinitions = void 0;
 const graph_client_1 = require("./graph-client");
 const ado_client_1 = require("./ado-client");
 const graph_endpoints_json_1 = __importDefault(require("./data/graph-endpoints.json"));
 const ado_endpoints_json_1 = __importDefault(require("./data/ado-endpoints.json"));
 const runtime_1 = require("../nerves/runtime");
 const MUTATE_METHODS = ["POST", "PATCH", "DELETE"];
-// Map HTTP method to authority action name for canWrite() checks
-const METHOD_TO_ACTION = {
-    POST: "createWorkItem",
-    PATCH: "updateWorkItem",
-    DELETE: "deleteWorkItem",
-};
-// Check if a tool response indicates a 403 PERMISSION_DENIED (authority checker removed; this is now a no-op kept for call-site stability)
-function checkAndRecord403(_result, _integration, _scope, _action, _ctx) {
-    // No-op: AuthorityChecker eliminated. 403 recording removed.
-}
 const DEFAULT_ADO_QUERY = "SELECT [System.Id], [System.Title], [System.State], [System.AssignedTo] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.State] <> 'Closed' ORDER BY [System.ChangedDate] DESC";
 exports.teamsToolDefinitions = [
     // -- Generic Graph tools --
@@ -46,6 +35,7 @@ exports.teamsToolDefinitions = [
             return (0, graph_client_1.graphRequest)(ctx.graphToken, "GET", args.path);
         },
         integration: "graph",
+        summaryKeys: ["path"],
     },
     {
         tool: {
@@ -74,7 +64,8 @@ exports.teamsToolDefinitions = [
             return (0, graph_client_1.graphRequest)(ctx.graphToken, args.method, args.path, args.body);
         },
         integration: "graph",
-        confirmationRequired: true,
+        summaryKeys: ["method", "path"],
+        riskProfile: { mutates: "external_side_effect", risk: "high", reason: "mutates Microsoft Graph resources" },
     },
     // -- Generic ADO tools --
     {
@@ -82,7 +73,7 @@ exports.teamsToolDefinitions = [
             type: "function",
             function: {
                 name: "ado_query",
-                description: "GET or POST (for WIQL read queries) any Azure DevOps API endpoint. Use ado_docs first to look up the correct path.",
+                description: "GET or POST (for WIQL read queries) any Azure DevOps API endpoint. Use ado_docs first to look up the correct path and host.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -90,6 +81,7 @@ exports.teamsToolDefinitions = [
                         path: { type: "string", description: "ADO API path after /{org}, e.g. /_apis/wit/wiql" },
                         method: { type: "string", enum: ["GET", "POST"], description: "HTTP method (defaults to GET)" },
                         body: { type: "string", description: "JSON request body (optional, used with POST for WIQL)" },
+                        host: { type: "string", description: "API host override for non-standard APIs (e.g. 'vsapm.dev.azure.com' for entitlements, 'vssps.dev.azure.com' for users). Omit for standard dev.azure.com." },
                     },
                     required: ["organization", "path"],
                 },
@@ -100,18 +92,17 @@ exports.teamsToolDefinitions = [
                 return "AUTH_REQUIRED:ado -- I need access to Azure DevOps. Please sign in when prompted.";
             }
             const method = args.method || "GET";
-            const result = await (0, ado_client_1.adoRequest)(ctx.adoToken, method, args.organization, args.path, args.body);
-            checkAndRecord403(result, "ado", args.organization, method, ctx);
-            return result;
+            return (0, ado_client_1.adoRequest)(ctx.adoToken, method, args.organization, args.path, args.body, args.host);
         },
         integration: "ado",
+        summaryKeys: ["method", "organization", "path"],
     },
     {
         tool: {
             type: "function",
             function: {
                 name: "ado_mutate",
-                description: "POST/PATCH/DELETE any Azure DevOps API endpoint for actual mutations. Use ado_docs first to look up the correct path.",
+                description: "POST/PATCH/DELETE any Azure DevOps API endpoint for actual mutations. Use ado_docs first to look up the correct path and host.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -119,6 +110,7 @@ exports.teamsToolDefinitions = [
                         organization: { type: "string", description: "Azure DevOps organization name" },
                         path: { type: "string", description: "ADO API path after /{org}" },
                         body: { type: "string", description: "JSON request body (optional)" },
+                        host: { type: "string", description: "API host override for non-standard APIs (e.g. 'vsapm.dev.azure.com' for entitlements, 'vssps.dev.azure.com' for users). Omit for standard dev.azure.com." },
                     },
                     required: ["method", "organization", "path"],
                 },
@@ -131,14 +123,11 @@ exports.teamsToolDefinitions = [
             if (!MUTATE_METHODS.includes(args.method)) {
                 return `Invalid method "${args.method}". Must be one of: ${MUTATE_METHODS.join(", ")}`;
             }
-            /* v8 ignore next -- fallback unreachable: method is validated against MUTATE_METHODS above @preserve */
-            const action = METHOD_TO_ACTION[args.method] || args.method;
-            const result = await (0, ado_client_1.adoRequest)(ctx.adoToken, args.method, args.organization, args.path, args.body);
-            checkAndRecord403(result, "ado", args.organization, action, ctx);
-            return result;
+            return (0, ado_client_1.adoRequest)(ctx.adoToken, args.method, args.organization, args.path, args.body, args.host);
         },
         integration: "ado",
-        confirmationRequired: true,
+        summaryKeys: ["method", "organization", "path"],
+        riskProfile: { mutates: "external_side_effect", risk: "high", reason: "mutates Azure DevOps resources" },
     },
     // -- Convenience aliases (backward compat) --
     {
@@ -157,6 +146,7 @@ exports.teamsToolDefinitions = [
             return (0, graph_client_1.getProfile)(ctx.graphToken);
         },
         integration: "graph",
+        summaryKeys: [],
     },
     {
         tool: {
@@ -200,6 +190,55 @@ exports.teamsToolDefinitions = [
             return (0, ado_client_1.queryWorkItems)(ctx.adoToken, org, query);
         },
         integration: "ado",
+        summaryKeys: ["organization", "query"],
+    },
+    // -- Proactive messaging --
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "teams_send_message",
+                description: "send a proactive 1:1 Teams message to a user. requires their AAD object ID (use graph_query /users to find it). the message appears as coming from the bot.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        user_id: { type: "string", description: "AAD object ID of the user to message" },
+                        user_name: { type: "string", description: "display name of the user (for logging)" },
+                        message: { type: "string", description: "message text to send" },
+                        tenant_id: { type: "string", description: "tenant ID (optional, defaults to current conversation tenant)" },
+                    },
+                    required: ["user_id", "message"],
+                },
+            },
+        },
+        /* v8 ignore start -- proactive messaging requires live Teams SDK conversation client @preserve */
+        handler: async (args, ctx) => {
+            if (!ctx?.botApi) {
+                return "proactive messaging is not available -- no bot API context (this tool only works in the Teams channel)";
+            }
+            try {
+                const tenantId = args.tenant_id || ctx.tenantId;
+                // Cast to the SDK's ConversationClient shape (kept as `unknown` in ToolContext to avoid type coupling)
+                const conversations = ctx.botApi.conversations;
+                const conversation = await conversations.create({
+                    bot: { id: ctx.botApi.id },
+                    members: [{ id: args.user_id, role: "user", name: args.user_name || args.user_id }],
+                    tenantId,
+                    isGroup: false,
+                });
+                await conversations.activities(conversation.id).create({
+                    type: "message",
+                    text: args.message,
+                });
+                return `message sent to ${args.user_name || args.user_id}`;
+            }
+            catch (e) {
+                return `failed to send proactive message: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        },
+        /* v8 ignore stop */
+        summaryKeys: ["user_name", "user_id"],
+        riskProfile: { mutates: "external_side_effect", risk: "high", reason: "sends a proactive Teams message" },
     },
     // -- Documentation tools --
     {
@@ -221,6 +260,7 @@ exports.teamsToolDefinitions = [
             return searchEndpoints(graph_endpoints_json_1.default, args.query || "");
         },
         integration: "graph",
+        summaryKeys: ["query"],
     },
     {
         tool: {
@@ -241,12 +281,9 @@ exports.teamsToolDefinitions = [
             return searchEndpoints(ado_endpoints_json_1.default, args.query || "");
         },
         integration: "ado",
+        summaryKeys: ["query"],
     },
 ];
-// Backward-compat: extract just the OpenAI tool schemas
-exports.teamsTools = exports.teamsToolDefinitions.map((d) => d.tool);
-// Backward-compat: extract just the handlers by name
-exports.teamsToolHandlers = Object.fromEntries(exports.teamsToolDefinitions.map((d) => [d.tool.function.name, d.handler]));
 function searchEndpoints(entries, query) {
     (0, runtime_1.emitNervesEvent)({
         component: "repertoire",
@@ -268,41 +305,10 @@ function searchEndpoints(entries, query) {
             `  ${e.description}`,
             `  Params: ${e.params || "none"}`,
         ];
+        if (e.host)
+            lines.push(`  Host: ${e.host}`);
         if (e.scopes)
             lines.push(`  Scopes: ${e.scopes}`);
         return lines.join("\n");
     }).join("\n\n");
 }
-function summarizeTeamsArgs(name, args) {
-    function summarizeKeyValues(keys) {
-        const parts = [];
-        for (const key of keys) {
-            const raw = args[key];
-            if (raw === undefined || raw === null)
-                continue;
-            const compact = String(raw).replace(/\s+/g, " ").trim();
-            if (!compact)
-                continue;
-            const clipped = compact.length > 60 ? compact.slice(0, 60) + "..." : compact;
-            parts.push(`${key}=${clipped}`);
-        }
-        return parts.join(" ");
-    }
-    if (name === "graph_profile")
-        return "";
-    if (name === "ado_work_items")
-        return summarizeKeyValues(["organization", "query"]);
-    if (name === "graph_query")
-        return summarizeKeyValues(["path"]);
-    if (name === "graph_mutate")
-        return summarizeKeyValues(["method", "path"]);
-    if (name === "ado_query")
-        return summarizeKeyValues(["method", "organization", "path"]);
-    if (name === "ado_mutate")
-        return summarizeKeyValues(["method", "organization", "path"]);
-    if (name === "graph_docs")
-        return summarizeKeyValues(["query"]);
-    if (name === "ado_docs")
-        return summarizeKeyValues(["query"]);
-    return undefined;
-}

package/dist/repertoire/tools-telegram-contacts.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.telegramContactToolDefinition = void 0;
+const runtime_1 = require("../nerves/runtime");
+exports.telegramContactToolDefinition = {
+    tool: { type: "function", function: {
+            name: "telegram_contact_manage",
+            description: "List household Telegram contacts, revoke one exact approved contact, or release one exact blocked contact request. Owner only; quarantined message text is never returned.",
+            parameters: { type: "object", properties: {
+                    action: { type: "string", enum: ["list", "revoke", "unblock"] },
+                    friendId: { type: "string", description: "Exact Friend ID from list; required for revoke." },
+                    admissionId: { type: "string", description: "Exact blocked admission ID from list; required for unblock." },
+                }, required: ["action"], additionalProperties: false },
+        } },
+    handler: async (args, ctx) => {
+        const actor = ctx?.relationshipAuthorization?.actor;
+        const manager = ctx?.telegramContactManager;
+        if (!actor || actor.trustLevel !== "family" || !manager)
+            return JSON.stringify({ ok: false, error: "Telegram contact management requires the live owner relationship" });
+        const action = String(args.action ?? "");
+        if (action === "list")
+            return JSON.stringify({ ok: true, ...(await manager.list({ actorFriendId: actor.friendId })) });
+        if (action === "revoke" && typeof args.friendId === "string" && args.friendId.trim())
+            return JSON.stringify({ ok: true, ...(await manager.revoke({ actorFriendId: actor.friendId, friendId: args.friendId })) });
+        if (action === "unblock" && typeof args.admissionId === "string" && args.admissionId.trim())
+            return JSON.stringify({ ok: true, ...(await manager.unblock({ actorFriendId: actor.friendId, admissionId: args.admissionId })) });
+        return JSON.stringify({ ok: false, error: "Telegram contact management arguments are invalid" });
+    },
+    riskProfile: (args) => String(args.action) === "list" ? { mutates: "none", risk: "low" } : { mutates: "durable_state_write", risk: "high", reason: "changes one exact household Telegram admission" },
+    approvalPolicy: () => ({ kind: "not_required" }),
+};
+(0, runtime_1.emitNervesEvent)({
+    component: "repertoire",
+    event: "repertoire.telegram_contact_tool_loaded",
+    message: "Telegram contact management tool loaded",
+    meta: { operations: 3 },
+});