paperclip-plugin-telegram 0.8.0 → 0.8.1

package/dist/command-definition-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-definition-validation.js","sourceRoot":"","sources":["../src/command-definition-validation.ts"],"names":[],"mappings":"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"}

package/dist/command-registry.d.ts

@@ -1,3 +1,64 @@
 import type { PluginContext } from "@paperclipai/plugin-sdk";
+export type WorkflowStepBase = {
+    id: string;
+    name?: string;
+};
+export type FetchIssueStep = WorkflowStepBase & {
+    type: "fetch_issue";
+    issueId: string;
+};
+export type InvokeAgentStep = WorkflowStepBase & {
+    type: "invoke_agent";
+    agentId: string;
+    prompt: string;
+};
+export type HttpRequestStep = WorkflowStepBase & {
+    type: "http_request";
+    url: string;
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    headers?: Record<string, string>;
+    body?: string;
+};
+export type SendMessageStep = WorkflowStepBase & {
+    type: "send_message";
+    text: string;
+};
+export type CreateIssueStep = WorkflowStepBase & {
+    type: "create_issue";
+    title: string;
+    description?: string;
+    projectId?: string;
+    assigneeAgentId?: string;
+};
+export type WaitApprovalStep = WorkflowStepBase & {
+    type: "wait_approval";
+    prompt: string;
+    timeoutMs?: number;
+};
+export type SetStateStep = WorkflowStepBase & {
+    type: "set_state";
+    key: string;
+    value: string;
+};
+export type WorkflowStep = FetchIssueStep | InvokeAgentStep | HttpRequestStep | SendMessageStep | CreateIssueStep | WaitApprovalStep | SetStateStep;
+export type CustomCommand = {
+    name: string;
+    description: string;
+    steps: WorkflowStep[];
+    createdBy: string;
+    createdAt: string;
+};
 export declare function handleCommandsCommand(ctx: PluginContext, token: string, chatId: string, args: string, messageThreadId?: number, companyId?: string): Promise<void>;
 export declare function tryCustomCommand(ctx: PluginContext, token: string, chatId: string, command: string, argsStr: string, messageThreadId?: number, companyId?: string): Promise<boolean>;
+/** True for the two callbacks a wait_approval step's buttons send back. */
+export declare function isWorkflowApprovalCallback(data: string): boolean;
+/**
+ * Resume or abandon a workflow parked at an approval gate.
+ *
+ * The parked state is deleted before the remaining steps run. That ordering is
+ * the point: it makes a second press of the same button a no-op instead of
+ * running the tail of the workflow twice. Telegram leaves the buttons on screen
+ * and re-delivers callbacks it considers unacknowledged, so a double press is
+ * the expected case, not the unlucky one.
+ */
+export declare function resolveWorkflowApprovalCallback(ctx: PluginContext, token: string, data: string, callbackQueryId: string, actor: string, messageId?: number): Promise<void>;

package/dist/command-registry.js

@@ -1,5 +1,18 @@
-import { sendMessage, escapeMarkdownV2, sendChatAction } from "./telegram-api.js";
+import { sendMessage, escapeMarkdownV2, sendChatAction, answerCallbackQuery, editMessage } from "./telegram-api.js";
 import { METRIC_NAMES } from "./constants.js";
+import { validateCommandDefinition } from "./command-definition-validation.js";
+/**
+ * Returned by a `wait_approval` step to tell executeWorkflow to stop and park.
+ * Carries the approval id so the continuation is stored under the same key the
+ * buttons will send back.
+ */
+const AWAITING_APPROVAL_PREFIX = "__awaiting_approval__:";
+/** Callback data prefixes for the two buttons a wait_approval step sends. */
+const APPROVE_PREFIX = "cmd_approve_";
+const REJECT_PREFIX = "cmd_reject_";
+function approvalStateKey(approvalId) {
+    return `cmd_approval_${approvalId}`;
+}
 // --- Built-in commands ---
 const BUILTIN_COMMANDS = new Set([
     "status", "issues", "agents", "approve", "help",
@@ -78,41 +91,31 @@ async function importCommand(ctx, token, chatId, jsonStr, messageThreadId, compa
         await sendMessage(ctx, token, chatId, "Usage: /commands import <json-definition>", { messageThreadId });
         return;
     }
-    let definition;
+    let parsed;
     try {
-        definition = JSON.parse(jsonStr);
+        parsed = JSON.parse(jsonStr);
     }
     catch {
         await sendMessage(ctx, token, chatId, "Invalid JSON. Please provide a valid command definition.", { messageThreadId });
         return;
     }
-    if (!definition.name || !definition.steps || !Array.isArray(definition.steps)) {
-        await sendMessage(ctx, token, chatId, "Command definition must have 'name' and 'steps' fields.", { messageThreadId });
+    const validation = validateCommandDefinition(parsed);
+    if (!validation.ok) {
+        await sendMessage(ctx, token, chatId, validation.error, { messageThreadId });
         return;
     }
+    const definition = validation.definition;
     if (BUILTIN_COMMANDS.has(definition.name)) {
         await sendMessage(ctx, token, chatId, `Cannot override built-in command: /${definition.name}`, { messageThreadId });
         return;
     }
-    // Validate steps
-    for (const step of definition.steps) {
-        if (!step.type || !step.id) {
-            await sendMessage(ctx, token, chatId, "Each step must have 'type' and 'id' fields.", { messageThreadId });
-            return;
-        }
-        const validTypes = ["fetch_issue", "invoke_agent", "http_request", "send_message", "create_issue", "wait_approval", "set_state"];
-        if (!validTypes.includes(step.type)) {
-            await sendMessage(ctx, token, chatId, `Invalid step type: ${step.type}. Valid: ${validTypes.join(", ")}`, { messageThreadId });
-            return;
-        }
-    }
     const resolvedCompanyId = companyId ?? chatId;
     const commands = await getCommandRegistry(ctx, resolvedCompanyId);
     // Replace existing or add new
     const existingIdx = commands.findIndex((c) => c.name === definition.name);
     const newCmd = {
         name: definition.name,
-        description: definition.description ?? "No description",
+        description: definition.description,
         steps: definition.steps,
         createdBy: `telegram:${chatId}`,
         createdAt: new Date().toISOString(),
@@ -152,13 +155,39 @@ async function runCommand(ctx, token, chatId, name, args, messageThreadId, compa
     await executeWorkflow(ctx, token, chatId, cmd, args, messageThreadId, resolvedCompanyId);
 }
 // --- Workflow executor ---
-async function executeWorkflow(ctx, token, chatId, cmd, args, messageThreadId, companyId) {
+async function executeWorkflow(ctx, token, chatId, cmd, args, messageThreadId, companyId, startIndex = 0, priorResults = []) {
     await sendChatAction(ctx, token, chatId);
-    await ctx.metrics.write(METRIC_NAMES.commandsExecuted, 1);
-    const results = [];
-    for (const step of cmd.steps) {
+    if (startIndex === 0) {
+        await ctx.metrics.write(METRIC_NAMES.commandsExecuted, 1);
+    }
+    const results = [...priorResults];
+    for (let index = startIndex; index < cmd.steps.length; index++) {
+        const step = cmd.steps[index];
         try {
             const result = await executeStep(ctx, token, chatId, step, args, results, messageThreadId, companyId);
+            // An approval gate stops the run here. Continuing would execute the very
+            // steps the gate exists to hold back — which is what this used to do,
+            // making the Approve button decorative.
+            if (typeof result === "string" && result.startsWith(AWAITING_APPROVAL_PREFIX)) {
+                const approvalId = result.slice(AWAITING_APPROVAL_PREFIX.length);
+                const parked = {
+                    commandName: cmd.name,
+                    args,
+                    results,
+                    nextStepIndex: index + 1,
+                    chatId,
+                    messageThreadId,
+                    companyId,
+                    createdAt: Date.now(),
+                };
+                await ctx.state.set({ scopeKind: "instance", stateKey: approvalStateKey(approvalId) }, parked);
+                ctx.logger.info("Workflow parked awaiting approval", {
+                    command: cmd.name,
+                    stepId: step.id,
+                    approvalId,
+                });
+                return;
+            }
             results.push({ stepId: step.id, result: result ?? "" });
         }
         catch (err) {
@@ -236,20 +265,35 @@ async function executeStep(ctx, token, chatId, step, args, prevResults, messageT
         }
         case "wait_approval": {
             const prompt = interpolate(step.prompt);
-            const approvalId = `cmd_approval_${Date.now()}`;
+            // Unique per step within a run: Date.now() alone collides when two steps
+            // park in the same millisecond, and a collision would resume the wrong
+            // continuation.
+            const approvalId = `${Date.now()}_${step.id}`;
             await sendMessage(ctx, token, chatId, prompt, {
                 messageThreadId,
                 inlineKeyboard: [
                     [
-                        { text: "Approve", callback_data: `cmd_approve_${approvalId}` },
-                        { text: "Reject", callback_data: `cmd_reject_${approvalId}` },
+                        { text: "Approve", callback_data: `${APPROVE_PREFIX}${approvalId}` },
+                        { text: "Reject", callback_data: `${REJECT_PREFIX}${approvalId}` },
                     ],
                 ],
             });
-            // Store approval state - workflow will be continued by callback handler
-            await ctx.state.set({ scopeKind: "instance", stateKey: `cmd_approval_${approvalId}` }, { status: "pending", createdAt: Date.now() });
-            return "awaiting_approval";
+            // executeWorkflow stores the continuation under this id and stops. The
+            // state is written there rather than here because only the loop knows
+            // which step comes next.
+            return `${AWAITING_APPROVAL_PREFIX}${approvalId}`;
         }
+        // NOTE: there is deliberately no "choice" step that blocks inline.
+        //
+        // A step that asks the user to pick and *awaits* the answer cannot work
+        // here: updates are processed strictly sequentially, so a workflow that
+        // blocks on a button press blocks the loop that would deliver it. The
+        // press can never arrive and the run stalls until it times out.
+        //
+        // `wait_approval` is how such a step has to be built instead: send the
+        // buttons, persist the continuation, return, and let the callback handler
+        // resume the run. A `choice` step can be added the same way — park the
+        // context keyed by an id and resolve it in resolveWorkflowApprovalCallback.
         case "set_state": {
             const key = interpolate(step.key);
             const value = interpolate(step.value);
@@ -260,6 +304,66 @@ async function executeStep(ctx, token, chatId, step, args, prevResults, messageT
             return null;
     }
 }
+// --- Approval callbacks ---
+/** True for the two callbacks a wait_approval step's buttons send back. */
+export function isWorkflowApprovalCallback(data) {
+    return data.startsWith(APPROVE_PREFIX) || data.startsWith(REJECT_PREFIX);
+}
+/**
+ * Resume or abandon a workflow parked at an approval gate.
+ *
+ * The parked state is deleted before the remaining steps run. That ordering is
+ * the point: it makes a second press of the same button a no-op instead of
+ * running the tail of the workflow twice. Telegram leaves the buttons on screen
+ * and re-delivers callbacks it considers unacknowledged, so a double press is
+ * the expected case, not the unlucky one.
+ */
+export async function resolveWorkflowApprovalCallback(ctx, token, data, callbackQueryId, actor, messageId) {
+    const approved = data.startsWith(APPROVE_PREFIX);
+    const approvalId = data.slice((approved ? APPROVE_PREFIX : REJECT_PREFIX).length);
+    const stateKey = approvalStateKey(approvalId);
+    const parked = await ctx.state.get({
+        scopeKind: "instance",
+        stateKey,
+    });
+    if (!parked || parked.resolved) {
+        // Already decided, or from a build before the continuation was persisted.
+        // Saying so beats silence, which would read as the button doing nothing.
+        await answerCallbackQuery(ctx, token, callbackQueryId, "This approval is no longer pending.");
+        return;
+    }
+    await ctx.state.set({ scopeKind: "instance", stateKey }, { ...parked, resolved: true });
+    if (!approved) {
+        await answerCallbackQuery(ctx, token, callbackQueryId, "Rejected");
+        if (messageId) {
+            await editMessage(ctx, token, parked.chatId, messageId, `Rejected by ${actor}. The workflow stopped here.`);
+        }
+        ctx.logger.info("Workflow rejected at approval gate", {
+            command: parked.commandName,
+            approvalId,
+            actor,
+        });
+        return;
+    }
+    await answerCallbackQuery(ctx, token, callbackQueryId, "Approved");
+    if (messageId) {
+        const edited = await editMessage(ctx, token, parked.chatId, messageId, `Approved by ${actor}. Continuing.`);
+        if (!edited) {
+            ctx.logger.error("editMessage after approval failed", {
+                chatId: parked.chatId,
+                messageId,
+            });
+        }
+    }
+    const commands = await getCommandRegistry(ctx, parked.companyId);
+    const cmd = commands.find((c) => c.name === parked.commandName);
+    if (!cmd) {
+        // The command was edited or deleted while the approval sat pending.
+        await sendMessage(ctx, token, parked.chatId, `Approved, but /${parked.commandName} no longer exists — nothing to continue.`, { messageThreadId: parked.messageThreadId });
+        return;
+    }
+    await executeWorkflow(ctx, token, parked.chatId, cmd, parked.args, parked.messageThreadId, parked.companyId, parked.nextStepIndex, parked.results);
+}
 // --- State helpers ---
 async function getCommandRegistry(ctx, companyId) {
     const commands = await ctx.state.get({

package/dist/command-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-registry.js","sourceRoot":"","sources":["../src/command-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command-registry.js","sourceRoot":"","sources":["../src/command-registry.ts"],"names":[],"mappings":"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"}

package/dist/commands.d.ts

@@ -4,7 +4,16 @@ type BotCommand = {
     description: string;
 };
 export declare const BOT_COMMANDS: BotCommand[];
-export declare function handleCommand(ctx: PluginContext, token: string, chatId: string, command: string, args: string, messageThreadId?: number, baseUrl?: string, publicUrl?: string, companyId?: string, boardApiToken?: string, maxAgentsPerThread?: number): Promise<void>;
+type HelpEntry = {
+    usage: string;
+    description: string;
+};
+type HelpGroup = {
+    title: string;
+    entries: HelpEntry[];
+};
+export declare const HELP_GROUPS: HelpGroup[];
+export declare function handleCommand(ctx: PluginContext, token: string, chatId: string, command: string, args: string, messageThreadId?: number, baseUrl?: string, publicUrl?: string, companyId?: string, boardApiToken?: string, maxAgentsPerThread?: number, connectCompanyIds?: readonly string[]): Promise<void>;
 export declare function handleConnectTopic(ctx: PluginContext, token: string, chatId: string, args: string, messageThreadId?: number): Promise<void>;
 export declare function getTopicForProject(ctx: PluginContext, chatId: string, projectName?: string): Promise<number | undefined>;
 export declare function resolveNotificationThreadId(ctx: PluginContext, chatId: string, event: PluginEvent, topicRouting: boolean): Promise<number | undefined>;

package/dist/commands.js

@@ -1,8 +1,10 @@
+import { JsonRpcCallError, PLUGIN_RPC_ERROR_CODES } from "@paperclipai/plugin-sdk";
 import { sendMessage, escapeMarkdownV2, sendChatAction } from "./telegram-api.js";
 import { METRIC_NAMES } from "./constants.js";
 import { countAgents } from "./agent-status.js";
 import { handleAcpCommand } from "./acp-bridge.js";
 import { buildPaperclipAuthHeaders, fetchPaperclipApi } from "./paperclip-api.js";
+import { str } from "./coerce.js";
 // Leaves headroom below Telegram's 4096-char hard limit for /agents so a
 // company with many agents doesn't produce a message the API silently drops.
 const AGENTS_MESSAGE_CHAR_BUDGET = 3500;
@@ -19,7 +21,47 @@ export const BOT_COMMANDS = [
     { command: "acp", description: "Manage agent sessions (spawn, status, cancel, close)" },
     { command: "commands", description: "Manage custom workflow commands (list, import, run, delete)" },
 ];
-export async function handleCommand(ctx, token, chatId, command, args, messageThreadId, baseUrl, publicUrl, companyId, boardApiToken, maxAgentsPerThread) {
+// Grouped by task rather than BOT_COMMANDS's flat menu order: a first-time
+// user scanning /help should be able to tell "what do I use for approvals"
+// at a glance, not read 11 undifferentiated lines. Every command in
+// BOT_COMMANDS appears in exactly one group here (enforced by a test).
+export const HELP_GROUPS = [
+    {
+        title: "Daily use",
+        entries: [
+            { usage: "/create <task title>", description: "Create a new task (assigned to CEO agent)" },
+            { usage: "/status", description: "Company health: active agents, open issues" },
+            { usage: "/issues [project]", description: "List open issues (optionally by project)" },
+            { usage: "/help", description: "Show available commands" },
+        ],
+    },
+    {
+        title: "Approvals",
+        entries: [{ usage: "/approve <approval-id>", description: "Approve a pending request by ID" }],
+    },
+    {
+        title: "Agent sessions",
+        entries: [
+            { usage: "/acp <spawn|status|cancel|close>", description: "Manage agent sessions" },
+            { usage: "/agents", description: "List agents with current status" },
+        ],
+    },
+    {
+        title: "Automation",
+        entries: [
+            { usage: "/commands <list|import|run|delete>", description: "Manage custom workflow commands" },
+        ],
+    },
+    {
+        title: "Setup",
+        entries: [
+            { usage: "/connect <company-name>", description: "Link this chat to a Paperclip company" },
+            { usage: "/connect_topic <project-name> [topic-id]", description: "Map a project to a forum topic" },
+            { usage: "/topics <list|remove|clear>", description: "List or remove forum topic mappings" },
+        ],
+    },
+];
+export async function handleCommand(ctx, token, chatId, command, args, messageThreadId, baseUrl, publicUrl, companyId, boardApiToken, maxAgentsPerThread, connectCompanyIds) {
     await ctx.metrics.write(METRIC_NAMES.commandsHandled, 1);
     switch (command) {
         case "create":
@@ -47,7 +89,7 @@ export async function handleCommand(ctx, token, chatId, command, args, messageTh
             await handleHelp(ctx, token, chatId, messageThreadId);
             break;
         case "connect":
-            await handleConnect(ctx, token, chatId, args, messageThreadId);
+            await handleConnect(ctx, token, chatId, args, messageThreadId, connectCompanyIds);
             break;
         case "connect_topic":
             await handleConnectTopic(ctx, token, chatId, args, messageThreadId);
@@ -203,31 +245,56 @@ async function handleApprove(ctx, token, chatId, approvalId, messageThreadId, ba
     }
 }
 async function handleHelp(ctx, token, chatId, messageThreadId) {
-    const lines = [
-        escapeMarkdownV2("📎") + " *Paperclip Bot Commands*",
-        "",
-        ...BOT_COMMANDS.map((cmd) => `/${escapeMarkdownV2(cmd.command)} \\- ${escapeMarkdownV2(cmd.description)}`),
-    ];
+    const lines = [escapeMarkdownV2("📎") + " *Paperclip Bot Commands*"];
+    for (const group of HELP_GROUPS) {
+        lines.push("");
+        lines.push(`*${escapeMarkdownV2(group.title)}*`);
+        for (const entry of group.entries) {
+            lines.push(`${escapeMarkdownV2(entry.usage)} \\- ${escapeMarkdownV2(entry.description)}`);
+        }
+    }
+    lines.push("");
+    lines.push(escapeMarkdownV2("Run a command with no arguments (e.g. /acp) to see its full usage."));
     await sendMessage(ctx, token, chatId, lines.join("\n"), {
         parseMode: "MarkdownV2",
         messageThreadId,
     });
 }
-async function handleConnect(ctx, token, chatId, companyArg, messageThreadId) {
+// Background commands cannot discover companies with an unscoped list call:
+// it races with live host invocations. IDs come from verified config deliveries;
+// re-reading each explicit company lets the host enforce current authorization.
+async function connectCompanies(ctx, companyIds) {
+    if (companyIds === undefined)
+        return ctx.companies.list();
+    const companies = await Promise.all(companyIds.map(async (id) => {
+        try {
+            return await ctx.companies.get(id);
+        }
+        catch (err) {
+            // Revoked scopes are unavailable, but a timeout or host failure must
+            // remain an error instead of masquerading as a missing company.
+            if (err instanceof JsonRpcCallError && err.code === PLUGIN_RPC_ERROR_CODES.INVOCATION_SCOPE_DENIED)
+                return null;
+            throw err;
+        }
+    }));
+    return companies.filter((company) => company !== null);
+}
+async function handleConnect(ctx, token, chatId, companyArg, messageThreadId, connectCompanyIds) {
     if (!companyArg.trim()) {
         try {
-            const companies = await ctx.companies.list();
+            const companies = await connectCompanies(ctx, connectCompanyIds);
             const names = companies.map((c) => c.name || c.id).join(", ");
             await sendMessage(ctx, token, chatId, `Usage: /connect <company-name>\nAvailable: ${names || "none"}`, { messageThreadId });
         }
         catch {
-            await sendMessage(ctx, token, chatId, "Usage: /connect <company-name>", { messageThreadId });
+            await sendMessage(ctx, token, chatId, "Usage: /connect <company-name>\nCould not load available companies. Please try again.", { messageThreadId });
         }
         return;
     }
     try {
         const input = companyArg.trim();
-        const companies = await ctx.companies.list();
+        const companies = await connectCompanies(ctx, connectCompanyIds);
         const match = companies.find((c) => c.id === input ||
             c.name?.toLowerCase() === input.toLowerCase());
         if (!match) {
@@ -518,10 +585,10 @@ export async function resolveNotificationThreadId(ctx, chatId, event, topicRouti
 }
 async function resolveEventProjectName(ctx, event) {
     const payload = event.payload;
-    const payloadProjectName = payload.projectName ? String(payload.projectName) : undefined;
+    const payloadProjectName = payload.projectName ? str(payload.projectName) : undefined;
     if (payloadProjectName)
         return payloadProjectName;
-    const payloadProjectId = payload.projectId ? String(payload.projectId) : undefined;
+    const payloadProjectId = payload.projectId ? str(payload.projectId) : undefined;
     if (payloadProjectId) {
         try {
             const project = await ctx.projects.get(payloadProjectId, event.companyId);