arisa 5.1.24 → 5.1.60

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

@@ -1,18 +1,18 @@
-import path from "node:path";
-import { readFile, stat, unlink } from "node:fs/promises";
-import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, defineTool } from "@earendil-works/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
+import { readFile, stat } from "node:fs/promises";
+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 } 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";
 
 const piValidationTimeoutMs = 60_000;
 const arisaToolNames = [
@@ -25,35 +25,11 @@ const arisaToolNames = [
   "list_scheduled_tasks",
   "cancel_scheduled_task",
   "cancel_all_scheduled_tasks",
+  "create_telegram_topic",
+  "initialize_telegram_topic",
   "send_artifact"
 ];
 
-function messageText(content) {
-  if (typeof content === "string") return content.trim();
-  if (!Array.isArray(content)) return "";
-  return content
-    .filter((item) => item?.type === "text" && typeof item.text === "string")
-    .map((item) => item.text.trim())
-    .filter(Boolean)
-    .join("\n");
-}
-
-export function formatPortableSessionHistory(messages = []) {
-  return messages
-    .map((message) => {
-      const text = messageText(message?.content);
-      if (!text) return "";
-      const role = message.role === "assistant"
-        ? "Assistant"
-        : message.role === "user"
-          ? "User"
-          : (message.customType ? `Session memory (${message.customType})` : "Session context");
-      return `${role}:\n${text}`;
-    })
-    .filter(Boolean)
-    .join("\n\n");
-}
-
 const estimatedImageTokens = 1_200;
 
 function estimateContentTokens(content) {
@@ -102,37 +78,14 @@ function summarizeRetainedContext(messages = []) {
   };
 }
 
-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 guardTools(tools, accessGuard) {
+  return tools.map((tool) => ({
+    ...tool,
+    execute: async (...args) => {
+      await accessGuard();
+      return tool.execute(...args);
+    }
+  }));
 }
 
 function isLocalBaseUrl(value) {
@@ -168,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()) {
@@ -225,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) {
@@ -242,114 +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({ contextInspectionTimeoutMs } = {}) {
-    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,
-      managedProcessIds: [],
-      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
-      );
-      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) {
@@ -388,7 +243,7 @@ export class AgentManager {
     return this.validatePiAgent(config);
   }
 
-  async getSessionContext(chatId, telegram) {
+  async getSessionContext(chatId, telegram, { scopeChatId = chatId, accessGuard = async () => {} } = {}) {
     const sessionKey = String(chatId);
     const modelSelection = resolveChatModelSelection(this.config, sessionKey);
     const effectiveModelId = modelSelection.model;
@@ -406,6 +261,8 @@ export class AgentManager {
           this.logger?.log("agent", `updating speed for chat ${sessionKey}: ${existing.speedController.speed}x -> ${desiredSpeed}x`);
           existing.speedController.setSpeed(desiredSpeed);
         }
+        existing.telegramTarget.current = telegram;
+        existing.accessGuardTarget.current = accessGuard;
         this.logger?.log("agent", `reusing session for chat ${sessionKey}`);
         return existing;
       }
@@ -438,10 +295,26 @@ export class AgentManager {
     );
     const hasExistingSession = sessionManager.buildSessionContext().messages.length > 0;
     this.logger?.log("agent", `${hasExistingSession ? "resuming" : "creating"} session for chat ${sessionKey} with model ${effectiveModelId} effort ${thinkingLevel} speed ${speed}x`);
-    const customTools = [
-      ...this.createTools(telegram, chatId, policy),
-      createSystemShellTool({ workspaceDir: policy.workspaceDir, shell: policy.shell })
-    ];
+    const telegramTarget = { current: telegram };
+    const accessGuardTarget = { current: accessGuard };
+    const telegramProxy = {
+      sendMedia: (...args) => telegramTarget.current.sendMedia(...args),
+      createForumTopic: (...args) => telegramTarget.current.createForumTopic(...args),
+      initializeForumTopic: (...args) => telegramTarget.current.initializeForumTopic(...args),
+      prepareRestartReceipt: (...args) => telegramTarget.current.prepareRestartReceipt(...args),
+      cancelRestartReceipt: (...args) => telegramTarget.current.cancelRestartReceipt(...args),
+      getTaskContext: (...args) => telegramTarget.current.getTaskContext?.(...args) || null
+    };
+    const assertAccess = () => accessGuardTarget.current();
+    const customTools = guardTools([
+      ...this.createTools(telegramProxy, scopeChatId, policy),
+      createSystemShellTool({
+        workspaceDir: policy.workspaceDir,
+        shell: policy.shell,
+        beforeRestart: (summary) => telegramProxy.prepareRestartReceipt(summary),
+        cancelRestart: (receiptId) => telegramProxy.cancelRestartReceipt(receiptId)
+      })
+    ], assertAccess);
     const settingsManager = createPiSettingsManager(this.config);
     const resourceLoader = await createArisaResourceLoader({
       cwd: policy.workspaceDir,
@@ -473,12 +346,16 @@ export class AgentManager {
       })}`);
     }
 
-    const ctx = { session, modelId: effectiveModelId, modelKey: effectiveModelKey, speedController };
+    const ctx = {
+      session,
+      modelId: effectiveModelId,
+      modelKey: effectiveModelKey,
+      speedController,
+      telegramTarget,
+      accessGuardTarget
+    };
     this.sessions.set(sessionKey, ctx);
-    if (isNewSession) {
-      this.pendingNewSessions.delete(sessionKey);
-      this.pendingSessionHandoffs.delete(sessionKey);
-    }
+    if (isNewSession) this.sessionLifecycle.completeNewSession(sessionKey);
     return ctx;
   }
 
@@ -497,18 +374,12 @@ 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 }) {
+  async runTool({ name, request, chatId, taskContext = null }) {
     await this.toolRegistry.load();
     this.logger?.log("agent", `run_tool ${name}`);
-    const chatArtifactStore = this.artifactStore.forChat(chatId);
     const resourceId = String(request?.resourceId || "").trim();
     const resourceNote = resourceId
       ? await this.resourceNotes.get(chatId, name, resourceId)
@@ -516,283 +387,24 @@ export class AgentManager {
     const enrichedRequest = resourceNote ? { ...request, resourceId, resourceNote } : request;
     const result = await this.toolRegistry.run({ name, request: enrichedRequest, chatId });
 
-    if (result.output?.text) {
-      const outArtifact = await chatArtifactStore.createText({
-        text: result.output.text,
-        source: { type: "tool", toolName: name },
-        metadata: { tool: name }
-      });
-      result.output.artifactId = outArtifact.id;
-    }
-
-    if (result.output?.filePath) {
-      const generated = await chatArtifactStore.createFromFile({
-        originalPath: result.output.filePath,
-        fileName: result.output.fileName || path.basename(result.output.filePath),
-        kind: result.output.kind || "file",
-        mimeType: result.output.mimeType || "application/octet-stream",
-        source: { type: "tool", toolName: name },
-        metadata: { tool: name, delivery: result.output.delivery }
-      });
-      result.output.artifactId = generated.id;
-      await unlink(result.output.filePath).catch(() => {});
-    }
-
-    if (result.asyncTask || result.asyncTasks?.length) {
-      const scheduled = await this.taskStore.addMany(
-        result.asyncTasks || [result.asyncTask],
-        {
-          payload: { chatId },
-          source: { type: "tool", toolName: name, chatId }
-        }
-      );
-      result.asyncTasks = scheduled;
-      delete result.asyncTask;
-    }
-
-    return result;
+    return materializeToolOutput({
+      result,
+      name,
+      chatId,
+      artifactStore: this.artifactStore,
+      taskStore: this.taskStore,
+      taskContext
+    });
   }
 
   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
-          });
-
-          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: "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
+    });
   }
+
 }