@asermax/tachikoma 2.0.0

package/dist/extensions/tasks/session-delivery.d.ts

@@ -0,0 +1,18 @@
+import type { Delivery } from "../../channels/types.ts";
+import type { Logger } from "../../log.ts";
+import type { TaskRepository } from "./repository.ts";
+import type { TaskDefinitionRecord, TaskInstanceRecord } from "./schema.ts";
+export interface SessionDeliveryDeps {
+    repository: TaskRepository;
+    deliver: (delivery: Delivery) => void;
+    maxHoldSeconds: number;
+    now: () => Date;
+    log: Logger;
+}
+export declare const renderSessionTaskText: (instance: TaskInstanceRecord, definition: TaskDefinitionRecord | null) => string;
+/**
+ * One delivery pass: route pending session instances to the user through the
+ * idle-gated channel delivery, walking the pending → running → completed
+ * lifecycle. A failed handoff rolls the instance back to pending for retry.
+ */
+export declare const deliverSessionTasks: ({ repository, deliver, maxHoldSeconds, now, log, }: SessionDeliveryDeps) => void;

package/dist/extensions/tasks/session-delivery.js

@@ -0,0 +1,39 @@
+export const renderSessionTaskText = (instance, definition) => {
+    const label = definition != null ? `Scheduled task: ${definition.name}` : "Scheduled task";
+    return `📋 ${label}\n\n${instance.prompt}`;
+};
+/**
+ * One delivery pass: route pending session instances to the user through the
+ * idle-gated channel delivery, walking the pending → running → completed
+ * lifecycle. A failed handoff rolls the instance back to pending for retry.
+ */
+export const deliverSessionTasks = ({ repository, deliver, maxHoldSeconds, now, log, }) => {
+    for (const instance of repository.getPendingInstances("session")) {
+        const definition = instance.definitionId != null ? repository.getDefinition(instance.definitionId) : null;
+        repository.updateInstance(instance.id, { status: "running", startedAt: now() });
+        try {
+            deliver({
+                text: renderSessionTaskText(instance, definition),
+                gate: "idle",
+                // The agent acts on the task inside the session; the user sees its response.
+                target: "agent",
+                maxHoldSeconds,
+                metadata: { kind: "session_task", instanceId: instance.id },
+            });
+        }
+        catch (error) {
+            // Roll back so the next tick retries — otherwise the row is stuck
+            // running with no delivery attached.
+            repository.updateInstance(instance.id, { status: "pending", startedAt: null });
+            log.error({ instanceId: instance.id, err: error }, "session task delivery failed");
+            continue;
+        }
+        repository.updateInstance(instance.id, {
+            status: "completed",
+            completedAt: now(),
+            result: "Delivered successfully",
+        });
+        log.info({ instanceId: instance.id }, "session task delivered");
+    }
+};
+//# sourceMappingURL=session-delivery.js.map

package/dist/extensions/tasks/session-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-delivery.js","sourceRoot":"","sources":["../../../src/extensions/tasks/session-delivery.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,QAA4B,EAC5B,UAAuC,EAC/B,EAAE;IACV,MAAM,KAAK,GAAG,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,mBAAmB,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC;IAE3F,OAAO,MAAM,KAAK,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAC;AAC7C,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,EAClC,UAAU,EACV,OAAO,EACP,cAAc,EACd,GAAG,EACH,GAAG,GACiB,EAAQ,EAAE;IAC9B,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,mBAAmB,CAAC,SAAS,CAAC,EAAE,CAAC;QACjE,MAAM,UAAU,GACd,QAAQ,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAEzF,UAAU,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QAEhF,IAAI,CAAC;YACH,OAAO,CAAC;gBACN,IAAI,EAAE,qBAAqB,CAAC,QAAQ,EAAE,UAAU,CAAC;gBACjD,IAAI,EAAE,MAAM;gBACZ,6EAA6E;gBAC7E,MAAM,EAAE,OAAO;gBACf,cAAc;gBACd,QAAQ,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,EAAE;aAC5D,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,kEAAkE;YAClE,qCAAqC;YACrC,UAAU,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/E,GAAG,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,8BAA8B,CAAC,CAAC;YACnF,SAAS;QACX,CAAC;QAED,UAAU,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,EAAE;YACrC,MAAM,EAAE,WAAW;YACnB,WAAW,EAAE,GAAG,EAAE;YAClB,MAAM,EAAE,wBAAwB;SACjC,CAAC,CAAC;QAEH,GAAG,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,EAAE,EAAE,wBAAwB,CAAC,CAAC;IAClE,CAAC;AACH,CAAC,CAAC"}

package/dist/extensions/tasks/tools.d.ts

@@ -0,0 +1,38 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import type { TaskRepository } from "./repository.ts";
+export interface ToolDeps {
+    repository: TaskRepository;
+    timezone: string | undefined;
+    now: () => Date;
+}
+export declare const CreateTaskParams: Type.TObject<{
+    name: Type.TString;
+    schedule: Type.TString;
+    type: Type.TUnsafe<"session" | "background">;
+    prompt: Type.TString;
+    enabled: Type.TOptional<Type.TBoolean>;
+}>;
+export declare const UpdateTaskParams: Type.TObject<{
+    task_id: Type.TString;
+    name: Type.TOptional<Type.TString>;
+    schedule: Type.TOptional<Type.TString>;
+    task_type: Type.TOptional<Type.TUnsafe<"session" | "background">>;
+    prompt: Type.TOptional<Type.TString>;
+    enabled: Type.TOptional<Type.TBoolean>;
+}>;
+export declare const ListTasksParams: Type.TObject<{
+    archived: Type.TOptional<Type.TBoolean>;
+}>;
+export declare const QueryTaskInstancesParams: Type.TObject<{
+    status: Type.TOptional<Type.TUnsafe<"completed" | "failed" | "running" | "pending" | "waiting">>;
+    task_type: Type.TOptional<Type.TUnsafe<"session" | "background">>;
+    definition_id: Type.TOptional<Type.TString>;
+    limit: Type.TOptional<Type.TNumber>;
+}>;
+export declare const handleCreateTask: ({ repository, timezone, now }: ToolDeps, args: Static<typeof CreateTaskParams>) => string;
+export declare const handleUpdateTask: ({ repository, timezone, now }: ToolDeps, args: Static<typeof UpdateTaskParams>) => string;
+export declare const handleListTasks: ({ repository, timezone }: ToolDeps, args: Static<typeof ListTasksParams>) => string;
+export declare const handleQueryTaskInstances: ({ repository, timezone }: ToolDeps, args: Static<typeof QueryTaskInstancesParams>) => string;
+/** pi extension factory exposing the task management tools to the agent. */
+export declare const createTaskToolsFactory: (deps: ToolDeps) => ExtensionFactory;

package/dist/extensions/tasks/tools.js

@@ -0,0 +1,181 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { formatInTimezone, formatSchedule, parseSchedule } from "./schedule.js";
+const SCHEDULE_DESCRIPTION = "Cron expression (e.g., '0 9 * * *' for daily at 9 AM), bare ISO datetime interpreted in the configured timezone (e.g., '2026-04-01T15:00:00'), or ISO datetime with 'Z'/offset for an explicit zone";
+export const CreateTaskParams = Type.Object({
+    name: Type.String({ description: "Human-readable task name" }),
+    schedule: Type.String({ description: SCHEDULE_DESCRIPTION }),
+    type: StringEnum(["session", "background"], {
+        description: "'session' (delivered during idle) or 'background' (isolated execution)",
+    }),
+    prompt: Type.String({ description: "Instruction the agent follows when the task fires" }),
+    enabled: Type.Optional(Type.Boolean({ description: "Whether the task is active (default true)" })),
+});
+export const UpdateTaskParams = Type.Object({
+    task_id: Type.String({ description: "ID of the task to update (get IDs from list_tasks)" }),
+    name: Type.Optional(Type.String({ description: "New human-readable name" })),
+    schedule: Type.Optional(Type.String({ description: SCHEDULE_DESCRIPTION })),
+    task_type: Type.Optional(StringEnum(["session", "background"], {
+        description: "Change type — 'session' or 'background'",
+    })),
+    prompt: Type.Optional(Type.String({ description: "New agent instruction" })),
+    enabled: Type.Optional(Type.Boolean({ description: "Enable or disable the task" })),
+});
+export const ListTasksParams = Type.Object({
+    archived: Type.Optional(Type.Boolean({
+        description: "Set true to show disabled (archived) tasks instead of active ones",
+    })),
+});
+export const QueryTaskInstancesParams = Type.Object({
+    status: Type.Optional(StringEnum(["pending", "running", "waiting", "completed", "failed"], {
+        description: "Filter by instance status",
+    })),
+    task_type: Type.Optional(StringEnum(["session", "background"], { description: "Filter by task type" })),
+    definition_id: Type.Optional(Type.String({ description: "Filter by parent task definition ID" })),
+    limit: Type.Optional(Type.Number({ description: "Maximum entries to return (default 20)" })),
+});
+const describeDefinition = (definition, timezone) => {
+    const status = definition.enabled ? "✓ enabled" : "✗ disabled";
+    const lastFired = definition.lastFiredAt != null
+        ? ` (last: ${formatInTimezone(definition.lastFiredAt, timezone)})`
+        : "";
+    return [
+        `- [${definition.id}] **${definition.name}** [${definition.taskType}] ${status}`,
+        `  Schedule: ${formatSchedule(definition.schedule, timezone)}${lastFired}`,
+        "",
+    ];
+};
+export const handleCreateTask = ({ repository, timezone, now }, args) => {
+    const schedule = parseSchedule(args.schedule, timezone, now());
+    const created = repository.createDefinition({
+        name: args.name,
+        schedule,
+        taskType: args.type,
+        prompt: args.prompt,
+        enabled: args.enabled ?? true,
+    });
+    return [
+        `Task '${created.name}' created successfully.`,
+        `- ID: ${created.id}`,
+        `- Type: ${created.taskType}`,
+        `- Schedule: ${formatSchedule(created.schedule, timezone)}`,
+        `- Enabled: ${created.enabled}`,
+    ].join("\n");
+};
+export const handleUpdateTask = ({ repository, timezone, now }, args) => {
+    const existing = repository.getDefinition(args.task_id);
+    if (existing == null)
+        throw new Error(`Task '${args.task_id}' not found.`);
+    const patch = {};
+    if (args.name != null)
+        patch.name = args.name;
+    if (args.prompt != null)
+        patch.prompt = args.prompt;
+    if (args.enabled != null)
+        patch.enabled = args.enabled;
+    if (args.task_type != null)
+        patch.taskType = args.task_type;
+    if (args.schedule != null) {
+        patch.schedule = parseSchedule(args.schedule, timezone, now());
+        // The old fire time is meaningless for a new schedule — one-shots require a
+        // null lastFiredAt to fire, and the cron anchor falls back gracefully.
+        patch.lastFiredAt = null;
+    }
+    if (Object.keys(patch).length === 0)
+        return "No updates provided.";
+    repository.updateDefinition(args.task_id, patch);
+    return `Task '${args.task_id}' updated successfully.`;
+};
+export const handleListTasks = ({ repository, timezone }, args) => {
+    const archived = args.archived ?? false;
+    const definitions = archived
+        ? repository.listDisabledDefinitions()
+        : repository.listEnabledDefinitions();
+    if (definitions.length === 0)
+        return `No ${archived ? "archived" : "active"} tasks found.`;
+    return [
+        "# Task Definitions",
+        "",
+        ...definitions.flatMap((definition) => describeDefinition(definition, timezone)),
+    ].join("\n");
+};
+export const handleQueryTaskInstances = ({ repository, timezone }, args) => {
+    const instances = repository.queryInstances({
+        status: args.status,
+        taskType: args.task_type,
+        definitionId: args.definition_id,
+        limit: args.limit ?? 20,
+    });
+    if (instances.length === 0)
+        return "No task instances found.";
+    const lines = ["# Task Instances", ""];
+    for (const instance of instances) {
+        lines.push(`- [${instance.id}] [${instance.taskType}] ${instance.status} — scheduled for ${formatInTimezone(instance.scheduledFor, timezone)}`);
+        if (instance.definitionId != null)
+            lines.push(`  Definition: ${instance.definitionId}`);
+        if (instance.result != null)
+            lines.push(`  Result: ${instance.result}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+};
+const textResult = (text) => ({
+    content: [{ type: "text", text }],
+    details: undefined,
+});
+/** pi extension factory exposing the task management tools to the agent. */
+export const createTaskToolsFactory = (deps) => (pi) => {
+    pi.registerTool({
+        name: "create_task",
+        label: "Create Task",
+        description: "Create a new scheduled task definition. Tasks fire on a cron schedule (recurring) or at an ISO datetime (one-shot); 'session' tasks are delivered into the conversation during idle time, 'background' tasks run autonomously in an isolated agent.",
+        promptSnippet: "Schedule recurring or one-shot tasks (reminders, checks, background work)",
+        promptGuidelines: [
+            "Use create_task when the user asks to be reminded, to schedule recurring work, or to run something later.",
+        ],
+        parameters: CreateTaskParams,
+        async execute(_toolCallId, params) {
+            return textResult(handleCreateTask(deps, params));
+        },
+    });
+    pi.registerTool({
+        name: "update_task",
+        label: "Update Task",
+        description: "Update an existing task definition. Only provided fields are updated; omitted fields remain unchanged. Disable a task with enabled=false instead of deleting it.",
+        promptSnippet: "Modify or enable/disable an existing scheduled task",
+        promptGuidelines: [
+            "Use update_task with enabled=false to archive a task the user no longer wants.",
+        ],
+        parameters: UpdateTaskParams,
+        async execute(_toolCallId, params) {
+            return textResult(handleUpdateTask(deps, params));
+        },
+    });
+    pi.registerTool({
+        name: "list_tasks",
+        label: "List Tasks",
+        description: "List task definitions. Each entry includes the task ID (needed for update_task and query_task_instances), name, type, schedule, and status. Pass archived=true to show disabled tasks.",
+        promptSnippet: "List scheduled task definitions",
+        promptGuidelines: [
+            "Check list_tasks before create_task to avoid scheduling duplicate tasks.",
+        ],
+        parameters: ListTasksParams,
+        async execute(_toolCallId, params) {
+            return textResult(handleListTasks(deps, params));
+        },
+    });
+    pi.registerTool({
+        name: "query_task_instances",
+        label: "Query Task Instances",
+        description: "Query task execution instances (individual firings of task definitions), optionally filtered by status, task type, or parent definition. Use this to check whether and when a task ran and what it produced.",
+        promptSnippet: "Inspect past and pending runs of scheduled tasks",
+        promptGuidelines: [
+            "Use query_task_instances when the user asks whether a scheduled task ran or what its outcome was.",
+        ],
+        parameters: QueryTaskInstancesParams,
+        async execute(_toolCallId, params) {
+            return textResult(handleQueryTaskInstances(deps, params));
+        },
+    });
+};
+//# sourceMappingURL=tools.js.map

package/dist/extensions/tasks/tools.js.map

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

package/dist/extensions/telegram/buttons.d.ts

@@ -0,0 +1,14 @@
+import type { InlineKeyboardMarkup } from "grammy/types";
+export declare const MAX_BUTTON_VALUE_BYTES = 58;
+export declare const MAX_BUTTON_COUNT = 100;
+export interface ButtonSpec {
+    label: string;
+    value: string;
+}
+export declare const packCallbackData: (value: string, singleUse: boolean) => string;
+export declare const unpackCallbackData: (data: string) => {
+    value: string;
+    singleUse: boolean;
+} | null;
+export declare const validateButtons: (rows: ButtonSpec[][]) => void;
+export declare const buildInlineKeyboard: (rows: ButtonSpec[][], singleUse: boolean) => InlineKeyboardMarkup;

package/dist/extensions/telegram/buttons.js

@@ -0,0 +1,49 @@
+// Telegram caps callback_data at 64 bytes; the 5-byte prefix leaves 58 for the value.
+export const MAX_BUTTON_VALUE_BYTES = 58;
+export const MAX_BUTTON_COUNT = 100;
+const SINGLE_USE_PREFIX = "btn1:";
+const MULTI_USE_PREFIX = "btnN:";
+export const packCallbackData = (value, singleUse) => `${singleUse ? SINGLE_USE_PREFIX : MULTI_USE_PREFIX}${value}`;
+export const unpackCallbackData = (data) => {
+    if (data.startsWith(SINGLE_USE_PREFIX)) {
+        return { value: data.slice(SINGLE_USE_PREFIX.length), singleUse: true };
+    }
+    if (data.startsWith(MULTI_USE_PREFIX)) {
+        return { value: data.slice(MULTI_USE_PREFIX.length), singleUse: false };
+    }
+    return null;
+};
+export const validateButtons = (rows) => {
+    if (rows.length === 0)
+        throw new Error("buttons must contain at least one row");
+    let total = 0;
+    rows.forEach((row, rowIndex) => {
+        if (row.length === 0) {
+            throw new Error(`row ${rowIndex} must contain at least one button`);
+        }
+        row.forEach((button, buttonIndex) => {
+            if (button.label.trim().length === 0) {
+                throw new Error(`button at row ${rowIndex} index ${buttonIndex} has an empty label`);
+            }
+            if (button.value.length === 0) {
+                throw new Error(`button at row ${rowIndex} index ${buttonIndex} has an empty value`);
+            }
+            const bytes = Buffer.byteLength(button.value, "utf8");
+            if (bytes > MAX_BUTTON_VALUE_BYTES) {
+                throw new Error(`button value "${button.value.slice(0, 20)}…" exceeds the ` +
+                    `${MAX_BUTTON_VALUE_BYTES}-byte limit (${bytes} bytes)`);
+            }
+            total += 1;
+        });
+    });
+    if (total > MAX_BUTTON_COUNT) {
+        throw new Error(`total button count (${total}) exceeds the cap (${MAX_BUTTON_COUNT})`);
+    }
+};
+export const buildInlineKeyboard = (rows, singleUse) => ({
+    inline_keyboard: rows.map((row) => row.map((button) => ({
+        text: button.label,
+        callback_data: packCallbackData(button.value, singleUse),
+    }))),
+});
+//# sourceMappingURL=buttons.js.map

package/dist/extensions/telegram/buttons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buttons.js","sourceRoot":"","sources":["../../../src/extensions/telegram/buttons.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC,MAAM,iBAAiB,GAAG,OAAO,CAAC;AAClC,MAAM,gBAAgB,GAAG,OAAO,CAAC;AAOjC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAa,EAAE,SAAkB,EAAU,EAAE,CAC5E,GAAG,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,gBAAgB,GAAG,KAAK,EAAE,CAAC;AAEhE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,IAAY,EAAgD,EAAE;IAC/F,IAAI,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACvC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC1E,CAAC;IAED,IAAI,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACtC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC1E,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAoB,EAAQ,EAAE;IAC5D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAEhF,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE;QAC7B,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,OAAO,QAAQ,mCAAmC,CAAC,CAAC;QACtE,CAAC;QAED,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE;YAClC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACrC,MAAM,IAAI,KAAK,CAAC,iBAAiB,QAAQ,UAAU,WAAW,qBAAqB,CAAC,CAAC;YACvF,CAAC;YAED,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,iBAAiB,QAAQ,UAAU,WAAW,qBAAqB,CAAC,CAAC;YACvF,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YACtD,IAAI,KAAK,GAAG,sBAAsB,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,iBAAiB;oBACzD,GAAG,sBAAsB,gBAAgB,KAAK,SAAS,CAC1D,CAAC;YACJ,CAAC;YAED,KAAK,IAAI,CAAC,CAAC;QACb,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,IAAI,KAAK,GAAG,gBAAgB,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,sBAAsB,gBAAgB,GAAG,CAAC,CAAC;IACzF,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,IAAoB,EACpB,SAAkB,EACI,EAAE,CAAC,CAAC;IAC1B,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAChC,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC,KAAK;QAClB,aAAa,EAAE,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC;KACzD,CAAC,CAAC,CACJ;CACF,CAAC,CAAC"}

package/dist/extensions/telegram/channel.d.ts

@@ -0,0 +1,39 @@
+import type { Bot } from "grammy";
+import type { Channel, ChannelRuntime, Delivery, Exchange } from "../../channels/types.ts";
+export interface TelegramChannelOptions {
+    chatId: number;
+    allowMedia: boolean;
+    pushNotifications: boolean;
+    mediaDir: string;
+    /** Abort the in-flight agent run — wired from sessions.abortExchange. */
+    stop: () => Promise<void>;
+}
+export declare const STOP_COMMAND = "/stop";
+export declare const STOP_ACKNOWLEDGEMENT = "\u23F9 Stopped.";
+export declare class TelegramChannel implements Channel {
+    readonly name = "telegram";
+    private readonly bot;
+    private readonly options;
+    private readonly mutex;
+    private runtime;
+    private lastInboundId;
+    private lastOutboundId;
+    private activeRenderer;
+    constructor(bot: Bot, options: TelegramChannelOptions);
+    /** Last message received from the user — target for react_to_message. */
+    get lastInboundMessageId(): number | null;
+    /** Last message this channel sent — target for pin_message. */
+    get lastOutboundMessageId(): number | null;
+    start(runtime: ChannelRuntime): Promise<void>;
+    respond({ events }: Exchange): Promise<void>;
+    deliver(delivery: Delivery): Promise<void>;
+    status(text: string): void;
+    stop(): Promise<void>;
+    private handleText;
+    /** Abort the in-flight run instead of submitting — "/stop" never reaches the agent. */
+    private handleStop;
+    private handleMedia;
+    private sendErrorNotice;
+    private runtimeOrThrow;
+    private log;
+}

package/dist/extensions/telegram/channel.js

@@ -0,0 +1,201 @@
+import { join } from "node:path";
+import { unpackCallbackData } from "./buttons.js";
+import { mapButtonTap, mapMediaMessage, mapTextMessage } from "./inbound.js";
+import { buildAttachment, downloadMedia, generateMediaFilename, MediaTooLargeError, resolveMedia, } from "./media.js";
+import { Mutex } from "./mutex.js";
+import { deliverText, startTyping } from "./sending.js";
+import { StreamRenderer } from "./streaming.js";
+export const STOP_COMMAND = "/stop";
+export const STOP_ACKNOWLEDGEMENT = "⏹ Stopped.";
+export class TelegramChannel {
+    name = "telegram";
+    bot;
+    options;
+    mutex = new Mutex();
+    runtime = null;
+    lastInboundId = null;
+    lastOutboundId = null;
+    activeRenderer = null;
+    constructor(bot, options) {
+        this.bot = bot;
+        this.options = options;
+    }
+    /** Last message received from the user — target for react_to_message. */
+    get lastInboundMessageId() {
+        return this.lastInboundId;
+    }
+    /** Last message this channel sent — target for pin_message. */
+    get lastOutboundMessageId() {
+        return this.lastOutboundId;
+    }
+    async start(runtime) {
+        this.runtime = runtime;
+        this.bot.on("message", async (ctx) => {
+            if (ctx.chat.id !== this.options.chatId)
+                return;
+            if (ctx.message.text != null) {
+                await this.handleText(ctx.message);
+            }
+            else {
+                await this.handleMedia(ctx.message);
+            }
+        });
+        this.bot.on("callback_query:data", async (ctx) => {
+            await ctx
+                .answerCallbackQuery()
+                .catch((error) => runtime.log.warn({ err: error }, "callback answer failed"));
+            if (ctx.callbackQuery.from.id !== this.options.chatId) {
+                runtime.log.debug({ userId: ctx.callbackQuery.from.id }, "dropping unauthorized tap");
+                return;
+            }
+            const unpacked = unpackCallbackData(ctx.callbackQuery.data);
+            if (unpacked == null) {
+                runtime.log.warn({ data: ctx.callbackQuery.data }, "unrecognized callback data");
+                return;
+            }
+            const messageId = ctx.callbackQuery.message?.message_id ?? null;
+            if (unpacked.singleUse && messageId != null) {
+                void this.bot.api
+                    .editMessageReplyMarkup(this.options.chatId, messageId)
+                    .catch((error) => runtime.log.warn({ err: error }, "keyboard removal failed"));
+            }
+            runtime.submit(mapButtonTap(unpacked.value, messageId));
+        });
+        this.bot.catch(({ error }) => {
+            runtime.log.error({ err: error }, "telegram update handling failed");
+        });
+        // init() validates the token via getMe before going live; start() resolves
+        // only when polling stops, so it runs detached.
+        await this.bot.init();
+        void this.bot
+            .start({
+            allowed_updates: ["message", "callback_query"],
+            onStart: (me) => runtime.log.info({ username: me.username }, "telegram bot polling"),
+        })
+            .catch((error) => runtime.log.error({ err: error }, "telegram polling crashed"));
+    }
+    async respond({ events }) {
+        const log = this.log();
+        await this.mutex.run(async () => {
+            const stopTyping = startTyping(this.bot.api, this.options.chatId, log);
+            const renderer = new StreamRenderer(this.bot.api, this.options.chatId, log);
+            this.activeRenderer = renderer;
+            try {
+                for await (const event of events) {
+                    switch (event.kind) {
+                        case "text":
+                            await renderer.appendText(event.text);
+                            break;
+                        case "tool-start":
+                            await renderer.showTransient(`⚙ ${event.toolName}`);
+                            break;
+                        case "status":
+                            await renderer.showTransient(event.text);
+                            break;
+                        case "error":
+                            await this.sendErrorNotice(event.message, log);
+                            break;
+                        default:
+                            break;
+                    }
+                }
+            }
+            finally {
+                this.activeRenderer = null;
+                stopTyping();
+            }
+            this.lastOutboundId = (await renderer.finalize()) ?? this.lastOutboundId;
+        });
+    }
+    async deliver(delivery) {
+        const log = this.log();
+        await this.mutex.run(async () => {
+            const lastId = await deliverText(this.bot.api, this.options.chatId, delivery.text, this.options.pushNotifications, log);
+            if (lastId != null)
+                this.lastOutboundId = lastId;
+        });
+    }
+    status(text) {
+        const renderer = this.activeRenderer;
+        if (renderer != null) {
+            void renderer
+                .showTransient(text)
+                .catch((error) => this.log().debug({ err: error }, "status rendering failed"));
+            return;
+        }
+        // No streaming message to surface the line in — show liveness via typing.
+        void this.bot.api
+            .sendChatAction(this.options.chatId, "typing")
+            .catch((error) => this.log().debug({ err: error }, "status typing action failed"));
+    }
+    async stop() {
+        if (this.bot.isRunning())
+            await this.bot.stop();
+    }
+    async handleText(message) {
+        if (message.text?.trim() === STOP_COMMAND) {
+            this.lastInboundId = message.message_id;
+            await this.handleStop();
+            return;
+        }
+        const inbound = mapTextMessage(message);
+        if (inbound == null)
+            return;
+        this.lastInboundId = message.message_id;
+        this.runtimeOrThrow().submit(inbound);
+    }
+    /** Abort the in-flight run instead of submitting — "/stop" never reaches the agent. */
+    async handleStop() {
+        const log = this.log();
+        try {
+            await this.options.stop();
+        }
+        catch (error) {
+            log.warn({ err: error }, "exchange abort failed");
+        }
+        await this.bot.api
+            .sendMessage(this.options.chatId, STOP_ACKNOWLEDGEMENT)
+            .catch((error) => log.warn({ err: error }, "stop acknowledgement failed"));
+    }
+    async handleMedia(message) {
+        const log = this.log();
+        if (!this.options.allowMedia) {
+            log.debug("ignoring media message — allowMedia is disabled");
+            return;
+        }
+        const resolved = resolveMedia(message);
+        if (resolved == null) {
+            log.debug("ignoring unresolvable media message");
+            return;
+        }
+        this.lastInboundId = message.message_id;
+        try {
+            const destPath = join(this.options.mediaDir, generateMediaFilename(resolved));
+            await downloadMedia(this.bot.api, this.bot.token, resolved, destPath);
+            this.runtimeOrThrow().submit(mapMediaMessage(message, buildAttachment(resolved, destPath)));
+        }
+        catch (error) {
+            log.warn({ err: error }, "media download failed");
+            const notice = error instanceof MediaTooLargeError
+                ? error.message
+                : "Failed to download the file. Please try again.";
+            await this.bot.api
+                .sendMessage(this.options.chatId, notice)
+                .catch((sendError) => log.warn({ err: sendError }, "media failure notice failed"));
+        }
+    }
+    async sendErrorNotice(message, log) {
+        await this.bot.api
+            .sendMessage(this.options.chatId, `⚠️ Error: ${message}`)
+            .catch((error) => log.warn({ err: error }, "error notice failed"));
+    }
+    runtimeOrThrow() {
+        if (this.runtime == null)
+            throw new Error("telegram channel not started");
+        return this.runtime;
+    }
+    log() {
+        return this.runtimeOrThrow().log;
+    }
+}
+//# sourceMappingURL=channel.js.map

package/dist/extensions/telegram/channel.js.map

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

package/dist/extensions/telegram/chunking.d.ts

@@ -0,0 +1,7 @@
+export declare const TELEGRAM_MAX_MESSAGE_LENGTH = 4096;
+/**
+ * Split text into chunks within Telegram's message length limit, preferring
+ * paragraph boundaries, then line boundaries, then a hard split that never
+ * cuts a surrogate pair in half.
+ */
+export declare const splitMessage: (text: string, limit?: number) => string[];