arisa 5.1.49 → 5.1.60

package/AGENTS.md

@@ -169,8 +169,6 @@ Beyond time-based scheduling, tools can drive an event queue that wakes the agen
 - `poll_tool`: a recurring checker the poller **runs directly as a tool** (no agent turn spent). The poller materializes its output with the same logic as `run_tool`, so any `agent_event` the checker emits is enqueued for the next tick. Its `recurrence` reschedules the next poll.
 - `agent_event`: an incoming event. The poller delivers it as a prompt so the active runtime evaluates it and decides the next action (it may stay silent).
 
-Tasks without a `runAt` fire immediately, so `agent_event` and the first `poll_tool` run on the next tick.
-
 The poller dispatches all three kinds, but only `agent_task` is exercised by a catalog tool today (`schedule-agent-task`). The following is the pattern to follow when a checker tool is built:
 
 How a tool wires its own polling:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arisa",
-  "version": "5.1.49",
+  "version": "5.1.60",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",

package/src/core/agent/agent-manager.js

@@ -1,18 +1,16 @@
-import path from "node:path";
-import { readFileSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
-import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, defineTool } from "@earendil-works/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
+import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { createPiRuntime, hasProviderAuth } from "./pi-runtime.js";
 import { resolveChatModelSelection } from "./model-selection.js";
 import { appendArisaAgentsFile, arisaAgentsFile, arisaInstallDir, buildAgentRuntimeContext } from "./runtime-context.js";
 import { withTimeout } from "./prompt-timeout.js";
-import { buildPiToolPolicy, getCoreCodingTools } from "./core-tools.js";
+import { buildPiToolPolicy } from "./core-tools.js";
 import { createSystemShellTool } from "./system-shell-tool.js";
 import { clampModelThinkingLevel } from "./pi-runtime.js";
 import { clampModelSpeed, createModelSpeedController } from "./model-speed.js";
-import { arisaHomeDir, getChatPiSessionsDir, sessionStartOperationalNotesFile } from "../../runtime/paths.js";
-import { searchOfficialToolCatalog } from "../tools/official-tool-catalog.js";
+import { arisaHomeDir } from "../../runtime/paths.js";
+import { AgentSessionLifecycle } from "./agent-session-lifecycle.js";
+import { createPiCapabilityTools } from "./pi-capability-tools.js";
 import { ToolResourceNoteStore } from "../tools/tool-resource-note-store.js";
 import { materializeToolOutput } from "../tools/tool-output-materializer.js";
 
@@ -32,35 +30,6 @@ const arisaToolNames = [
   "send_artifact"
 ];
 
-const operationalNoteMaxChars = 220;
-
-function normalizeOperationalNote(note) {
-  const text = typeof note === "string" ? note : note?.text;
-  const trimmed = String(text || "").replace(/\s+/g, " ").trim();
-  if (!trimmed) return "";
-  return trimmed.length <= operationalNoteMaxChars ? trimmed : `${trimmed.slice(0, operationalNoteMaxChars - 1).trim()}…`;
-}
-
-export function loadSessionStartOperationalNotes() {
-  try {
-    const raw = readFileSync(sessionStartOperationalNotesFile, "utf8");
-    const parsed = JSON.parse(raw);
-    const notes = Array.isArray(parsed) ? parsed : parsed?.notes;
-    if (!Array.isArray(notes)) return [];
-    return notes.map(normalizeOperationalNote).filter(Boolean).slice(0, 20);
-  } catch {
-    return [];
-  }
-}
-
-function formatSessionStartOperationalNotes(notes) {
-  if (!notes.length) return "";
-  return [
-    "Durable operating notes for this Arisa session:",
-    ...notes.map((note) => `- ${note}`)
-  ].join("\n");
-}
-
 const estimatedImageTokens = 1_200;
 
 function estimateContentTokens(content) {
@@ -119,39 +88,6 @@ function guardTools(tools, accessGuard) {
   }));
 }
 
-function closeAgentSession(session) {
-  if (session?.close) return session.close();
-  if (session?.dispose) return session.dispose();
-  return undefined;
-}
-
-export const defaultScheduledTaskListLimit = 50;
-export const maxScheduledTaskListLimit = 100;
-
-export function selectScheduledTasks(tasks = [], { status, limit = defaultScheduledTaskListLimit } = {}) {
-  const parsedLimit = Number(limit);
-  const resolvedLimit = Math.min(
-    Math.max(Number.isFinite(parsedLimit) ? Math.trunc(parsedLimit) : defaultScheduledTaskListLimit, 1),
-    maxScheduledTaskListLimit
-  );
-  const allTasks = Array.isArray(tasks) ? tasks : [];
-  const orderedTasks = status
-    ? [...allTasks].reverse()
-    : [
-        ...allTasks.filter((task) => task.status === "pending" || task.status === "running").reverse(),
-        ...allTasks.filter((task) => task.status !== "pending" && task.status !== "running").reverse()
-      ];
-  const visibleTasks = orderedTasks.slice(0, resolvedLimit);
-
-  return {
-    tasks: visibleTasks,
-    total: allTasks.length,
-    returned: visibleTasks.length,
-    limit: resolvedLimit,
-    truncated: visibleTasks.length < allTasks.length
-  };
-}
-
 function isLocalBaseUrl(value) {
   if (typeof value !== "string" || !value.trim()) return false;
   try {
@@ -185,32 +121,6 @@ async function promptAndThrowOnAssistantError(session, prompt) {
   }
 }
 
-function inferDeliveryMethod(artifact) {
-  if (artifact.kind === "audio" || (artifact.mimeType || "").startsWith("audio/")) return "audio";
-  if (artifact.kind === "image" || (artifact.mimeType || "").startsWith("image/")) return "photo";
-  if (artifact.kind === "video" || (artifact.mimeType || "").startsWith("video/")) return "video";
-  return "document";
-}
-
-function containsAbsolutePath(value) {
-  if (typeof value !== "string") return false;
-  return /(^|\s)(\/[^\s]|[A-Za-z]:[\\/])/.test(value);
-}
-
-export function resolveMediaCaption(caption) {
-  if (caption && !containsAbsolutePath(caption)) return caption;
-  return undefined;
-}
-
-async function deliverArtifactToChat({ artifact, telegram, caption, method, logger }) {
-  const resolvedMethod = method || artifact.metadata?.delivery?.method || inferDeliveryMethod(artifact);
-  const fileName = path.basename(artifact.path);
-  const resolvedCaption = resolveMediaCaption(caption);
-  logger?.log("agent", `deliver artifact ${artifact.id} as ${resolvedMethod}`);
-  await telegram.sendMedia(artifact.path, { method: resolvedMethod, caption: resolvedCaption, filename: fileName });
-  return { method: resolvedMethod, fileName, artifactId: artifact.id };
-}
-
 async function assertDirectory(dir, label) {
   const stats = await stat(dir);
   if (!stats.isDirectory()) {
@@ -242,11 +152,21 @@ export class AgentManager {
     this.taskStore = taskStore;
     this.logger = logger;
     this.resourceNotes = new ToolResourceNoteStore();
-    this.sessions = new Map();
-    this.pendingNewSessions = new Set();
-    this.pendingSessionHandoffs = new Map();
+    this.sessionLifecycle = new AgentSessionLifecycle({
+      logger,
+      summarizeContext: summarizeRetainedContext
+    });
+    this.sessions = this.sessionLifecycle.sessions;
+    this.pendingNewSessions = this.sessionLifecycle.pendingNewSessions;
+    this.pendingSessionHandoffs = this.sessionLifecycle.pendingSessionHandoffs;
+    this.sessionClosePromises = this.sessionLifecycle.sessionClosePromises;
     this.artifactDeliveryHandler = null;
-    this.sessionClosePromises = new Map();
+    this.capabilityService = null;
+  }
+
+  setCapabilityService(capabilityService) {
+    if (!capabilityService?.execute) throw new Error("AgentManager requires CapabilityService");
+    this.capabilityService = capabilityService;
   }
 
   setArtifactDeliveryHandler(handler) {
@@ -259,122 +179,32 @@ export class AgentManager {
   }
 
   closeCachedSession(sessionKey) {
-    const key = String(sessionKey);
-    const existing = this.sessions.get(key);
-    this.sessions.delete(key);
-    const closeSession = (existing?.session?.close || existing?.session?.dispose)
-      ? () => closeAgentSession(existing.session)
-      : null;
-    if (!closeSession) {
-      return this.sessionClosePromises.get(key) || Promise.resolve();
-    }
-
-    const previousClose = this.sessionClosePromises.get(key);
-    const closePromise = Promise.resolve(previousClose)
-      .catch(() => {})
-      .then(closeSession)
-      .catch((error) => {
-        this.logger?.error?.("agent", `session close failed for chat ${key}: ${error instanceof Error ? error.message : String(error)}`);
-      })
-      .finally(() => {
-        if (this.sessionClosePromises.get(key) === closePromise) {
-          this.sessionClosePromises.delete(key);
-        }
-      });
-    this.sessionClosePromises.set(key, closePromise);
-    return closePromise;
+    return this.sessionLifecycle.closeCached(sessionKey);
   }
 
-  async waitForSessionClose(sessionKey) {
-    const key = String(sessionKey);
-    let closing = this.sessionClosePromises.get(key);
-    while (closing) {
-      await closing;
-      closing = this.sessionClosePromises.get(key);
-    }
+  waitForSessionClose(sessionKey) {
+    return this.sessionLifecycle.waitForClose(sessionKey);
   }
 
   setConfig(config) {
-    for (const key of this.sessions.keys()) this.closeCachedSession(key);
+    this.sessionLifecycle.resetConfigState();
     this.config = config;
-    this.pendingNewSessions.clear();
-    this.pendingSessionHandoffs.clear();
   }
 
-  resetSession(chatId, { handoff = "", parentSession = "" } = {}) {
-    const sessionKey = String(chatId);
-    this.closeCachedSession(sessionKey);
-    this.pendingNewSessions.add(sessionKey);
-    const text = String(handoff || "").trim();
-    const parent = String(parentSession || "").trim();
-    if (text || parent) {
-      this.pendingSessionHandoffs.set(sessionKey, { text, parentSession: parent });
-    } else {
-      this.pendingSessionHandoffs.delete(sessionKey);
-    }
+  resetSession(chatId, options = {}) {
+    this.sessionLifecycle.resetSession(chatId, options);
   }
 
   clearSessionCache(chatId) {
-    this.closeCachedSession(String(chatId));
+    this.sessionLifecycle.closeCached(String(chatId));
   }
 
-  async getRuntimeDiagnostic() {
-    const contexts = await Promise.all([...this.sessions.entries()].map(async ([chatId, context]) => {
-      const base = { chatId };
-      try {
-        const stats = context.session.getSessionStats();
-        const retained = summarizeRetainedContext(context.session.messages);
-        return {
-          ...base,
-          ...retained,
-          tokens: stats.contextUsage?.tokens ?? null,
-          contextWindow: stats.contextUsage?.contextWindow ?? null,
-          percent: stats.contextUsage?.percent ?? null
-        };
-      } catch (error) {
-        return { ...base, error: error instanceof Error ? error.message : String(error) };
-      }
-    }));
-    return {
-      harness: "pi",
-      sessions: this.sessions.size,
-      closingSessions: this.sessionClosePromises.size,
-      contexts
-    };
+  getRuntimeDiagnostic() {
+    return this.sessionLifecycle.getDiagnostic();
   }
 
   createSessionManager(chatId, workspaceDir = arisaInstallDir, sessionRevision = 0) {
-    const sessionKey = String(chatId);
-    const sessionDir = getChatPiSessionsDir(sessionKey, sessionRevision);
-    if (this.pendingNewSessions.has(sessionKey)) {
-      this.logger?.log("agent", `starting new persisted session for chat ${sessionKey}`);
-      const handoff = this.pendingSessionHandoffs.get(sessionKey);
-      const sessionManager = SessionManager.create(
-        workspaceDir,
-        sessionDir,
-        handoff?.parentSession ? { parentSession: handoff.parentSession } : undefined
-      );
-      const operationalNotes = formatSessionStartOperationalNotes(loadSessionStartOperationalNotes());
-      if (operationalNotes) {
-        sessionManager.appendCustomMessageEntry(
-          "arisa-operational-notes",
-          operationalNotes,
-          false,
-          { source: "session-start" }
-        );
-      }
-      if (handoff?.text) {
-        sessionManager.appendCustomMessageEntry(
-          "arisa-session-handoff",
-          handoff.text,
-          false,
-          { source: "telegram-new" }
-        );
-      }
-      return { sessionManager, isNewSession: true };
-    }
-    this.logger?.log("agent", `recovering persisted session for chat ${sessionKey}`);
-    return { sessionManager: SessionManager.continueRecent(workspaceDir, sessionDir), isNewSession: false };
+    return this.sessionLifecycle.createSessionManager(chatId, workspaceDir, sessionRevision);
   }
 
   async validatePiAgent(config = this.config) {
@@ -525,10 +355,7 @@ export class AgentManager {
       accessGuardTarget
     };
     this.sessions.set(sessionKey, ctx);
-    if (isNewSession) {
-      this.pendingNewSessions.delete(sessionKey);
-      this.pendingSessionHandoffs.delete(sessionKey);
-    }
+    if (isNewSession) this.sessionLifecycle.completeNewSession(sessionKey);
     return ctx;
   }
 
@@ -547,12 +374,7 @@ export class AgentManager {
   }
 
   async close() {
-    const contexts = [...this.sessions.values()];
-    this.sessions.clear();
-    await Promise.allSettled([
-      ...this.sessionClosePromises.values(),
-      ...contexts.map((context) => closeAgentSession(context.session))
-    ]);
+    await this.sessionLifecycle.closeAll();
   }
 
   async runTool({ name, request, chatId, taskContext = null }) {
@@ -576,285 +398,13 @@ export class AgentManager {
   }
 
   createTools(telegram, chatId, policy = buildPiToolPolicy({ config: this.config, customToolNames: arisaToolNames })) {
-    const chatArtifactStore = this.artifactStore.forChat(chatId);
-
-    return [
-      defineTool({
-        name: "list_tools",
-        label: "List tools",
-        description: "List Arisa tools, or search installed tool metadata by capability with automatic official-catalog fallback.",
-        parameters: Type.Object({ query: Type.Optional(Type.String()) }),
-        execute: async (_id, params) => {
-          await this.toolRegistry.load();
-          const coreTools = getCoreCodingTools({
-            tools: policy.tools,
-            excludeTools: policy.excludeTools
-          });
-          const nativeTools = [{
-            name: "system_shell",
-            source: "arisa-native",
-            description: "Run native system shell commands in the active Arisa workspace.",
-            workspaceDir: policy.workspaceDir,
-            shell: policy.shell.shellPath || (process.platform === "win32" ? "powershell" : "sh"),
-            enabled: !(policy.excludeTools || []).includes("system_shell")
-          }];
-          const query = params.query?.trim() || "";
-          let catalogFallback = null;
-          const cliTools = query
-            ? this.toolRegistry.search(query).map((tool) => ({
-              ...tool,
-              source: "arisa-modular",
-              invocation: "run_tool"
-            }))
-            : (await this.toolRegistry.listWithRuntime(chatId)).map((tool) => ({
-              ...tool,
-              source: "arisa-modular",
-              invocation: "run_tool"
-            }));
-          if (query && cliTools.length === 0) {
-            try {
-              catalogFallback = await searchOfficialToolCatalog(query);
-            } catch (error) {
-              catalogFallback = { unavailable: true, error: error?.message || String(error), matches: [] };
-            }
-          }
-          const result = {
-            query: query || null,
-            workspaceDir: policy.workspaceDir,
-            coreTools: query ? [] : coreTools,
-            nativeTools: query ? [] : nativeTools,
-            cliTools,
-            officialCatalogMatches: Array.isArray(catalogFallback) ? catalogFallback : catalogFallback?.matches || [],
-            catalogFallback: catalogFallback && !Array.isArray(catalogFallback) ? catalogFallback : null,
-            tools: query ? cliTools : [...coreTools.filter((tool) => tool.enabled), ...nativeTools.filter((tool) => tool.enabled), ...cliTools]
-          };
-          return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-            details: result
-          };
-        }
-      }),
-      defineTool({
-        name: "tool_help",
-        label: "Tool help",
-        description: "Show --help text for a CLI tool.",
-        parameters: Type.Object({ name: Type.String() }),
-        execute: async (_id, params) => {
-          await this.toolRegistry.load();
-          const help = await this.toolRegistry.help(params.name);
-          return { content: [{ type: "text", text: help }], details: { help } };
-        }
-      }),
-      defineTool({
-        name: "tool_skills",
-        label: "Tool skills",
-        description: "Show skills assigned to a CLI tool via its manifest skillHints.",
-        parameters: Type.Object({ name: Type.String() }),
-        execute: async (_id, params) => {
-          await this.toolRegistry.load();
-          const skills = await this.toolRegistry.resolveSkills(params.name);
-          const visible = skills.map(({ content, ...item }) => item);
-          return { content: [{ type: "text", text: JSON.stringify(visible, null, 2) }], details: visible };
-        }
-      }),
-      defineTool({
-        name: "set_tool_config",
-        label: "Set tool config",
-        description: "Write a tool config value scoped to the current chat.",
-        parameters: Type.Object({ name: Type.String(), field: Type.String(), value: Type.String() }),
-        execute: async (_id, params) => {
-          await this.toolRegistry.load();
-          const result = await this.toolRegistry.setConfig(params.name, params.field, params.value, chatId);
-          return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
-        }
-      }),
-      defineTool({
-        name: "set_tool_resource_note",
-        label: "Set tool resource note",
-        description: "Set or clear a deterministic chat-scoped note of up to 200 characters for one tool resource.",
-        parameters: Type.Object({
-          name: Type.String(),
-          resourceId: Type.String(),
-          note: Type.String()
-        }),
-        execute: async (_id, params) => {
-          const result = await this.resourceNotes.set(chatId, params.name, params.resourceId, params.note);
-          return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
-        }
-      }),
-      defineTool({
-        name: "run_tool",
-        label: "Run tool",
-        description: "Run a CLI tool using text input or an artifactId. Inspect the returned status/resolution fields. If a tool reports missing config, ask the user naturally, use set_tool_config, and retry. Set `deliver: true` to also send the generated file to the chat in one step (only when you want the user to receive it now, not for intermediate pipe steps).",
-        parameters: Type.Object({
-          name: Type.String(),
-          artifactId: Type.Optional(Type.String()),
-          text: Type.Optional(Type.String()),
-          resourceId: Type.Optional(Type.String()),
-          args: Type.Optional(Type.Record(Type.String(), Type.String())),
-          deliver: Type.Optional(Type.Boolean())
-        }),
-        execute: async (_id, params) => {
-          let artifact = null;
-          if (params.artifactId) {
-            artifact = await chatArtifactStore.get(params.artifactId);
-            if (!artifact) {
-              return { content: [{ type: "text", text: `Artifact not found: ${params.artifactId}` }], details: { ok: false } };
-            }
-          }
-          const result = await this.runTool({
-            name: params.name,
-            request: {
-              artifact,
-              text: params.text,
-              resourceId: params.resourceId,
-              args: params.args || {}
-            },
-            chatId,
-            taskContext: telegram.getTaskContext()
-          });
-
-          if (params.deliver && result.output?.artifactId) {
-            const generated = await chatArtifactStore.get(result.output.artifactId);
-            if (generated?.path) {
-              result.sent = await deliverArtifactToChat({ artifact: generated, telegram, logger: this.logger });
-            }
-          }
-
-          return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-            details: result
-          };
-        }
-      }),
-      defineTool({
-        name: "list_scheduled_tasks",
-        label: "List scheduled tasks",
-        description: "List scheduled async tasks for the current Telegram chat. Results default to 50 tasks, always include pending/running tasks, and accept an optional limit up to 100.",
-        parameters: Type.Object({
-          status: Type.Optional(Type.String()),
-          limit: Type.Optional(Type.Integer({ minimum: 1, maximum: maxScheduledTaskListLimit }))
-        }),
-        execute: async (_id, params) => {
-          const tasks = await this.taskStore.list({ chatId, status: params.status });
-          const result = selectScheduledTasks(tasks, {
-            status: params.status,
-            limit: params.limit
-          });
-          return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-            details: result
-          };
-        }
-      }),
-      defineTool({
-        name: "cancel_scheduled_task",
-        label: "Cancel scheduled task",
-        description: "Cancel one scheduled async task by id for the current Telegram chat.",
-        parameters: Type.Object({ id: Type.String() }),
-        execute: async (_id, params) => {
-          const existing = await this.taskStore.get(params.id);
-          if (!existing || existing.payload?.chatId !== chatId) {
-            return {
-              content: [{ type: "text", text: JSON.stringify({ ok: false, error: "Task not found" }) }],
-              details: { ok: false, error: "Task not found" }
-            };
-          }
-          const task = await this.taskStore.cancel(params.id);
-          return {
-            content: [{ type: "text", text: JSON.stringify({ ok: true, task }, null, 2) }],
-            details: { ok: true, task }
-          };
-        }
-      }),
-      defineTool({
-        name: "cancel_all_scheduled_tasks",
-        label: "Cancel all scheduled tasks",
-        description: "Cancel all pending or running async tasks for the current Telegram chat.",
-        parameters: Type.Object({}),
-        execute: async () => {
-          const tasks = await this.taskStore.cancelAll({ chatId });
-          return {
-            content: [{ type: "text", text: JSON.stringify({ ok: true, cancelled: tasks.length }, null, 2) }],
-            details: { ok: true, tasks }
-          };
-        }
-      }),
-      defineTool({
-        name: "create_telegram_topic",
-        label: "Create Telegram topic",
-        description: "Create and initialize a new topic in the current owner-only Telegram forum. Topic names are dynamic, and context seeds the isolated session without copying unrelated history.",
-        parameters: Type.Object({
-          name: Type.String({ minLength: 1, maxLength: 128 }),
-          context: Type.String({ minLength: 1, maxLength: 4000 })
-        }),
-        execute: async (_id, params) => {
-          if (typeof telegram.createForumTopic !== "function") {
-            const result = { ok: false, error: "Telegram topic creation is unavailable in this chat." };
-            return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
-          }
-          const result = await telegram.createForumTopic(params.name.trim(), params.context.trim());
-          return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
-        }
-      }),
-      defineTool({
-        name: "initialize_telegram_topic",
-        label: "Initialize Telegram topic",
-        description: "Seed or replace the isolated context of an existing topic in the current owner-only Telegram forum.",
-        parameters: Type.Object({
-          messageThreadId: Type.Integer({ minimum: 2 }),
-          name: Type.String({ minLength: 1, maxLength: 128 }),
-          context: Type.String({ minLength: 1, maxLength: 4000 })
-        }),
-        execute: async (_id, params) => {
-          if (typeof telegram.initializeForumTopic !== "function") {
-            const result = { ok: false, error: "Telegram topic initialization is unavailable in this chat." };
-            return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
-          }
-          const result = await telegram.initializeForumTopic({
-            messageThreadId: params.messageThreadId,
-            name: params.name.trim(),
-            context: params.context.trim()
-          });
-          return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
-        }
-      }),
-      defineTool({
-        name: "send_artifact",
-        label: "Send artifact",
-        description: "Deliver an existing chat artifact to the current Telegram chat. Pass the `artifactId` returned by run_tool or from an inbound file. The delivery method and filename are derived from the artifact (its delivery hint, kind, and stored name); internal local paths are never exposed. No caption is shown by default, since the filename already appears on the attachment; set `caption` only to add a separate visible label, or `method` to override the delivery method. The artifact is not deleted.",
-        parameters: Type.Object({
-          artifactId: Type.String(),
-          caption: Type.Optional(Type.String()),
-          method: Type.Optional(Type.Union([
-            Type.Literal("voice"),
-            Type.Literal("audio"),
-            Type.Literal("document")
-          ]))
-        }),
-        execute: async (_id, params) => {
-          const artifact = await chatArtifactStore.get(params.artifactId);
-          if (!artifact) {
-            const result = { ok: false, status: "failed", error: `Artifact not found: ${params.artifactId}` };
-            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
-          }
-          if (!artifact.path) {
-            const result = { ok: false, status: "failed", error: `Artifact ${params.artifactId} has no file to deliver.` };
-            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
-          }
-          const sent = await deliverArtifactToChat({
-            artifact,
-            telegram,
-            caption: params.caption,
-            method: params.method,
-            logger: this.logger
-          });
-          return {
-            content: [{ type: "text", text: `Media sent to Telegram as ${sent.method}.` }],
-            details: { ok: true, sent }
-          };
-        }
-      })
-    ];
+    return createPiCapabilityTools({
+      capabilityService: this.capabilityService,
+      telegram,
+      chatId,
+      policy,
+      logger: this.logger
+    });
   }
+
 }