pim-agent 0.0.1 → 0.10.0

package/packages/telegram/src/TaskSchema.ts

@@ -0,0 +1,88 @@
+import { type Static, Type } from "typebox";
+
+export type ScheduleSpec =
+  | { readonly type: "once"; readonly at: string }
+  | { readonly type: "interval"; readonly every: string }
+  | { readonly type: "cron"; readonly expr: string };
+
+export type ScheduledTask = {
+  readonly id: string;
+  readonly prompt: string;
+  readonly chatId: number;
+  readonly threadId: number | undefined;
+  readonly schedule: ScheduleSpec;
+  readonly status: "active" | "paused";
+  readonly nextRun: string;
+  readonly expires: string | null;
+  readonly isolatedSession: boolean;
+  readonly createdAt: string;
+};
+
+const scheduleSchema = Type.Union([
+  Type.Object({
+    type: Type.Literal("once"),
+    at: Type.String({
+      description:
+        "RFC3339 timestamp in the future, UTC. Example: '2026-05-14T15:30:00Z'.",
+    }),
+  }),
+  Type.Object({
+    type: Type.Literal("interval"),
+    every: Type.String({
+      description:
+        "Duration like '30m', '2h', '1h30m'. Units: s, m, h, d. Minimum 1 minute.",
+    }),
+  }),
+  Type.Object({
+    type: Type.Literal("cron"),
+    expr: Type.String({
+      description:
+        "Standard 5-field cron expression in UTC. Macros @hourly, @daily, @weekly, @monthly, @yearly supported.",
+    }),
+  }),
+]);
+
+export const taskToolSchema = Type.Object({
+  action: Type.Union(
+    [
+      Type.Literal("create"),
+      Type.Literal("list"),
+      Type.Literal("delete"),
+      Type.Literal("pause"),
+      Type.Literal("resume"),
+      Type.Literal("update_prompt"),
+    ],
+    {
+      description:
+        "create: schedule a new task. list: see this thread's tasks. delete/pause/resume: by id. update_prompt: change a task's prompt.",
+    }
+  ),
+  prompt: Type.Optional(
+    Type.String({
+      description:
+        "Required for 'create' and 'update_prompt'. The instruction the agent will receive when the task fires.",
+      minLength: 1,
+    })
+  ),
+  schedule: Type.Optional(scheduleSchema),
+  expires: Type.Optional(
+    Type.String({
+      description:
+        "Optional RFC3339 timestamp after which the task auto-deletes without firing again.",
+    })
+  ),
+  isolatedSession: Type.Optional(
+    Type.Boolean({
+      description:
+        "If true, run in a fresh/isolated session with no chat history. Default false.",
+    })
+  ),
+  id: Type.Optional(
+    Type.String({
+      description:
+        "Task id. Required for delete, pause, resume, update_prompt.",
+    })
+  ),
+});
+
+export type TaskToolInput = Static<typeof taskToolSchema>;

package/packages/telegram/src/TaskStore.ts

@@ -0,0 +1,67 @@
+import { readdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+import { Fs } from "#core/shared/Fs";
+import type { ScheduledTask } from "./TaskSchema";
+
+async function loadAll(
+  configDir: string
+): Promise<ReadonlyArray<ScheduledTask>> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir(configDir));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+  const loaded = await Promise.all(
+    entries
+      .filter((name) => name.endsWith(".json"))
+      .map((name) =>
+        Fs.readJsonOrEmpty<ScheduledTask | undefined>(
+          join(dir(configDir), name),
+          undefined
+        )
+      )
+  );
+  return loaded.filter(
+    (data): data is ScheduledTask =>
+      !!data && typeof data === "object" && "id" in data
+  );
+}
+
+async function save(configDir: string, task: ScheduledTask): Promise<void> {
+  await Fs.writeAtomic(path(configDir, task.id), JSON.stringify(task, null, 2));
+}
+
+async function remove(configDir: string, id: string): Promise<void> {
+  try {
+    await unlink(path(configDir, id));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw err;
+    }
+  }
+}
+
+function makeId(prompt: string): string {
+  const slug = prompt
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return slug ? `${slug}-${rand}` : rand;
+}
+
+function dir(configDir: string): string {
+  return join(configDir, "tasks");
+}
+
+function path(configDir: string, id: string): string {
+  return join(dir(configDir), `${id}.json`);
+}
+
+export const TaskStore = { loadAll, save, remove, makeId };

package/packages/telegram/src/TaskTool.ts

@@ -0,0 +1,208 @@
+import {
+  defineTool,
+  type AgentToolResult,
+} from "@earendil-works/pi-coding-agent";
+
+import type { PimToolDefinition } from "#core/shared/Tools";
+import type { Span, ToolView } from "#core/view/ViewBlock";
+import type { SessionId } from "./Session";
+import type { TaskScheduler } from "./TaskScheduler";
+import {
+  taskToolSchema,
+  type ScheduledTask,
+  type TaskToolInput,
+} from "./TaskSchema";
+
+export type TaskToolDeps = {
+  readonly scheduler: TaskScheduler;
+  readonly sessionId: SessionId;
+};
+
+function build(deps: TaskToolDeps): PimToolDefinition<typeof taskToolSchema> {
+  return {
+    ...defineTool({
+      name: "task",
+      label: "task",
+      description:
+        "Manage scheduled/recurring tasks for this Telegram chat/thread.",
+      parameters: taskToolSchema,
+      async execute(_id, params) {
+        const input = params as TaskToolInput;
+        switch (input.action) {
+          case "create":
+            return await create(deps, input);
+          case "list":
+            return await list(deps);
+          case "delete":
+            return await deleteTask(deps, input);
+          case "pause":
+          case "resume":
+            return await setStatus(deps, input);
+          case "update_prompt":
+            return await updatePrompt(deps, input);
+        }
+      },
+    }),
+    toViewModel: ({ args }): ToolView => ({
+      label: "Task",
+      icon: "clock",
+      title: [
+        {
+          kind: "spans",
+          spans: taskSpans((args ?? {}) as Partial<TaskToolInput>),
+        },
+      ],
+    }),
+  };
+}
+
+async function create(
+  deps: TaskToolDeps,
+  input: TaskToolInput
+): Promise<AgentToolResult<unknown>> {
+  const prompt = required(input, "prompt");
+  const schedule = required(input, "schedule");
+  const task = await deps.scheduler.create(deps.sessionId, {
+    prompt,
+    schedule,
+    expires: input.expires,
+    isolatedSession: input.isolatedSession,
+  });
+  return text(`Created task ${task.id}. Next run: ${task.nextRun}.`, task);
+}
+
+async function list(deps: TaskToolDeps): Promise<AgentToolResult<unknown>> {
+  const tasks = await deps.scheduler.list(deps.sessionId);
+  return tasks.length === 0
+    ? text("No tasks scheduled for this thread.", { tasks: [] })
+    : text(JSON.stringify(tasks), { tasks });
+}
+
+async function deleteTask(
+  deps: TaskToolDeps,
+  input: TaskToolInput
+): Promise<AgentToolResult<unknown>> {
+  const id = required(input, "id");
+  const ok = await deps.scheduler.delete(deps.sessionId, id);
+  if (!ok) {
+    throw notFound(id);
+  }
+  return text(`Deleted task ${id}.`, { id });
+}
+
+async function setStatus(
+  deps: TaskToolDeps,
+  input: TaskToolInput
+): Promise<AgentToolResult<unknown>> {
+  const id = required(input, "id");
+  const paused = input.action === "pause";
+  const task = found(
+    await deps.scheduler.setStatus(
+      deps.sessionId,
+      id,
+      paused ? "paused" : "active"
+    ),
+    id
+  );
+  return text(
+    paused
+      ? `Paused task ${task.id}. Will not fire until resumed.`
+      : `Resumed task ${task.id}. Next run: ${task.nextRun}.`,
+    task
+  );
+}
+
+async function updatePrompt(
+  deps: TaskToolDeps,
+  input: TaskToolInput
+): Promise<AgentToolResult<unknown>> {
+  const id = required(input, "id");
+  const prompt = required(input, "prompt");
+  const task = found(
+    await deps.scheduler.updatePrompt(deps.sessionId, id, prompt),
+    id
+  );
+  return text(`Updated prompt for task ${task.id}.`, task);
+}
+
+function text(message: string, details: unknown): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text" as const, text: message }],
+    details,
+  };
+}
+
+function required<K extends "id" | "prompt" | "schedule">(
+  input: TaskToolInput,
+  field: K
+): NonNullable<TaskToolInput[K]> {
+  const value = input[field];
+  if (!value) {
+    throw new Error(`'${field}' is required for action=${input.action}`);
+  }
+  return value;
+}
+
+function found(task: ScheduledTask | undefined, id: string): ScheduledTask {
+  if (!task) {
+    throw notFound(id);
+  }
+  return task;
+}
+
+function notFound(id: string): Error {
+  return new Error(`no task with id=${id} in this thread`);
+}
+
+function taskSpans(input: Partial<TaskToolInput>): readonly Span[] {
+  const action = input.action;
+  if (!action) {
+    return [{ text: "..." }];
+  }
+  if (action === "list") {
+    return [{ text: "List tasks" }];
+  }
+  if (action === "create") {
+    const schedule = scheduleSummary(input);
+    return [
+      { text: "Schedule task" },
+      ...(input.prompt ? [{ text: ": " }, code(input.prompt)] : []),
+      ...(schedule ? [{ text: ` (${schedule})` }] : []),
+    ];
+  }
+  if (action === "update_prompt") {
+    return input.prompt
+      ? [{ text: "Update task: " }, code(input.prompt)]
+      : [{ text: "Update task" }];
+  }
+  const verb = VERBS[action] ?? action;
+  return input.id
+    ? [{ text: `${verb} task: ` }, code(input.id)]
+    : [{ text: `${verb} task` }];
+}
+
+const VERBS: Readonly<Record<string, string>> = {
+  delete: "Delete",
+  pause: "Pause",
+  resume: "Resume",
+};
+
+function code(text: string): Span {
+  return { text, code: true };
+}
+
+function scheduleSummary(input: Partial<TaskToolInput>): string | undefined {
+  const schedule = input.schedule;
+  if (!schedule) {
+    return undefined;
+  }
+  if (schedule.type === "once") {
+    return `once @ ${schedule.at}`;
+  }
+  if (schedule.type === "interval") {
+    return `every ${schedule.every}`;
+  }
+  return `cron ${schedule.expr}`;
+}
+
+export const TaskTool = { build };

package/packages/telegram/src/TelegramHtml.ts

@@ -0,0 +1,288 @@
+import { Markdown } from "./Markdown";
+
+export const BR = "<br>";
+
+const MESSAGE_LIMIT = 32000;
+const BLOCK_TAGS = new Set([
+  "blockquote",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "ol",
+  "p",
+  "pre",
+  "table",
+  "tg-math-block",
+  "ul",
+]);
+const VOID_BLOCK_TAGS = new Set(["br", "hr"]);
+
+type HtmlTag = {
+  readonly start: number;
+  readonly end: number;
+  readonly name: string;
+  readonly closing: boolean;
+  readonly selfClosing: boolean;
+};
+
+function capStatus(text: string): string {
+  if (text.length <= MESSAGE_LIMIT) {
+    return text;
+  }
+  const blocks = splitStatusBlocks(text);
+  let dropped = 0;
+  while (blocks.length > 1) {
+    blocks.shift();
+    dropped += 1;
+    const rest = trimLeadingBreaks(blocks.join("").trimStart());
+    const candidate = `<p>… ${dropped} earlier entries</p>${rest}`;
+    if (candidate.length <= MESSAGE_LIMIT) {
+      return candidate;
+    }
+  }
+  return capPlainStatus(blocks);
+}
+
+function splitStatusBlocks(html: string): string[] {
+  const blocks: string[] = [];
+  let cursor = 0;
+  while (cursor < html.length) {
+    const tag = nextStatusBlockTag(html, cursor);
+    if (!tag) {
+      pushStatusBlock(blocks, html.slice(cursor));
+      break;
+    }
+    if (VOID_BLOCK_TAGS.has(tag.name)) {
+      pushStatusBlock(blocks, html.slice(cursor, tag.end));
+      cursor = tag.end;
+      continue;
+    }
+    pushStatusBlock(blocks, html.slice(cursor, tag.start));
+    const end = statusBlockEnd(html, tag);
+    pushStatusBlock(blocks, html.slice(tag.start, end));
+    cursor = end;
+  }
+  return blocks;
+}
+
+function nextStatusBlockTag(html: string, start: number): HtmlTag | undefined {
+  const tags = htmlTags(html, start);
+  for (const tag of tags) {
+    if (tag.closing) {
+      continue;
+    }
+    if (BLOCK_TAGS.has(tag.name) || VOID_BLOCK_TAGS.has(tag.name)) {
+      return tag;
+    }
+  }
+  return undefined;
+}
+
+function statusBlockEnd(html: string, opener: HtmlTag): number {
+  if (opener.selfClosing) {
+    return opener.end;
+  }
+  const stack = [opener.name];
+  const tags = htmlTags(html, opener.end);
+  for (const tag of tags) {
+    if (VOID_BLOCK_TAGS.has(tag.name)) {
+      continue;
+    }
+    if (!BLOCK_TAGS.has(tag.name)) {
+      continue;
+    }
+    if (tag.closing) {
+      if (stack.at(-1) === tag.name) {
+        stack.pop();
+      }
+    } else if (!tag.selfClosing) {
+      stack.push(tag.name);
+    }
+    if (stack.length === 0) {
+      return tag.end;
+    }
+  }
+  return html.length;
+}
+
+function* htmlTags(html: string, start: number): Generator<HtmlTag> {
+  const re = /<\s*(\/)?\s*([a-z][\w:-]*)(?:\s[^>]*)?\/?\s*>/gi;
+  re.lastIndex = start;
+  for (let match = re.exec(html); match; match = re.exec(html)) {
+    const raw = match[0]!;
+    yield {
+      start: match.index,
+      end: re.lastIndex,
+      name: match[2]!.toLowerCase(),
+      closing: match[1] !== undefined,
+      selfClosing: /\/\s*>$/.test(raw),
+    };
+  }
+}
+
+function pushStatusBlock(blocks: string[], block: string): void {
+  if (block) {
+    blocks.push(block);
+  }
+}
+
+function trimLeadingBreaks(text: string): string {
+  return text.replace(/^(?:<br\s*\/?>)+/i, "").trimStart();
+}
+
+function capPlainStatus(blocks: readonly string[]): string {
+  let head = "";
+  for (let i = 0; i < blocks.length; i++) {
+    const block = blocks[i]!;
+    const candidate = `${head}${block}`;
+    if (candidate.length <= MESSAGE_LIMIT) {
+      head = candidate;
+      continue;
+    }
+    const remaining = MESSAGE_LIMIT - head.length;
+    const truncated = truncateHtmlHead(block, remaining);
+    if (truncated) {
+      head = `${head}${truncated}`;
+    }
+    break;
+  }
+  return head.trimEnd();
+}
+
+function truncateHtmlHead(html: string, limit: number): string {
+  if (html.length <= limit) {
+    return html;
+  }
+  if (limit <= 0) {
+    return "";
+  }
+  const wrapper = outerHtmlWrapper(html);
+  if (wrapper) {
+    const innerLimit = limit - wrapper.open.length - wrapper.close.length;
+    if (innerLimit > 0) {
+      const inner = truncateHtmlHead(wrapper.inner, innerLimit);
+      if (inner) {
+        return `${wrapper.open}${inner}${wrapper.close}`;
+      }
+    }
+  }
+  return escapePlainHead(stripHtml(html), limit);
+}
+
+function outerHtmlWrapper(html: string):
+  | {
+      readonly open: string;
+      readonly inner: string;
+      readonly close: string;
+    }
+  | undefined {
+  const opener = /^<\s*([a-z][\w:-]*)(?:\s[^>]*)?\/?\s*>/i.exec(html);
+  if (!opener) {
+    return undefined;
+  }
+  const open = opener[0]!;
+  if (/\/\s*>$/.test(open)) {
+    return undefined;
+  }
+  const name = opener[1]!.toLowerCase();
+  const close = matchingHtmlCloseTag(html, name, open.length);
+  if (!close || close.end !== html.length) {
+    return undefined;
+  }
+  return {
+    open,
+    inner: html.slice(open.length, close.start),
+    close: html.slice(close.start, close.end),
+  };
+}
+
+function matchingHtmlCloseTag(
+  html: string,
+  name: string,
+  start: number
+): HtmlTag | undefined {
+  let depth = 1;
+  const tags = htmlTags(html, start);
+  for (const tag of tags) {
+    if (tag.name !== name) {
+      continue;
+    }
+    if (tag.closing) {
+      depth -= 1;
+      if (depth === 0) {
+        return tag;
+      }
+    } else if (!tag.selfClosing && !VOID_BLOCK_TAGS.has(tag.name)) {
+      depth += 1;
+    }
+  }
+  return undefined;
+}
+
+function escapePlainHead(text: string, limit: number): string {
+  const marker = "…";
+  if (limit < marker.length) {
+    return "";
+  }
+  const budget = limit - marker.length;
+  const escaped: string[] = [];
+  let length = 0;
+  for (const char of text) {
+    const next = char === "\n" ? BR : Markdown.escape(char);
+    if (length + next.length > budget) {
+      break;
+    }
+    escaped.push(next);
+    length += next.length;
+  }
+  return `${escaped.join("").trimEnd()}${marker}`;
+}
+
+function chunk(html: string): readonly string[] {
+  if (html.length <= MESSAGE_LIMIT) {
+    return [html];
+  }
+  const chunks: string[] = [];
+  let rest = html;
+  while (rest.length > MESSAGE_LIMIT) {
+    const idx = rest.lastIndexOf(BR, MESSAGE_LIMIT);
+    if (idx > 0) {
+      chunks.push(rest.slice(0, idx).trim());
+      rest = rest.slice(idx + BR.length).trim();
+    } else {
+      chunks.push(rest.slice(0, MESSAGE_LIMIT).trim());
+      rest = rest.slice(MESSAGE_LIMIT).trim();
+    }
+  }
+  if (rest) {
+    chunks.push(rest);
+  }
+  return chunks;
+}
+
+function sanitize(text: string): string {
+  return text.replace(
+    /\b(api[_-]?key|token|secret)\b\s*[:=]\s*\S+/gi,
+    "$1=[redacted]"
+  );
+}
+
+function stripHtml(html: string): string {
+  return html
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, "&");
+}
+
+export const TelegramHtml = {
+  cap: capStatus,
+  chunk,
+  sanitize,
+  strip: stripHtml,
+};

package/packages/telegram/src/TypingIndicator.ts

@@ -0,0 +1,43 @@
+import type { Api } from "grammy";
+
+import type { SessionId } from "./Session";
+
+export class TypingIndicator {
+  private readonly api: Api;
+  private readonly sessionId: SessionId;
+  private timer: Timer | undefined;
+  private stopped = true;
+
+  public constructor(api: Api, sessionId: SessionId) {
+    this.api = api;
+    this.sessionId = sessionId;
+  }
+
+  public start(): void {
+    if (this.timer) {
+      return;
+    }
+    this.stopped = false;
+    void this.send();
+    this.timer = setInterval(() => void this.send(), 4_000);
+  }
+
+  public stop(): void {
+    this.stopped = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  private async send(): Promise<void> {
+    if (this.stopped) {
+      return;
+    }
+    await this.api
+      .sendChatAction(this.sessionId.chatId, "typing", {
+        message_thread_id: this.sessionId.threadId,
+      })
+      .catch(() => {});
+  }
+}