pim-agent 0.0.1 → 0.9.0

package/packages/telegram/src/Session.ts

@@ -0,0 +1,252 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { Api } from "grammy";
+import { rename } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { AgentRuntime } from "#core/session/AgentRuntime";
+import {
+  SessionHost,
+  type HostSettings,
+  type SessionCompactResult,
+  type SetCwdResult,
+  type SetModelResult,
+} from "#core/session/SessionHost";
+import { Tools } from "#core/shared/Tools";
+import type { LogsMode, TelegramConfig, ThinkingLevelOpt } from "./Config";
+import { SendFileTool } from "./SendFileTool";
+import type { TaskScheduler } from "./TaskScheduler";
+import { TaskTool } from "./TaskTool";
+
+export type { SessionCompactResult, SetCwdResult, SetModelResult };
+
+export type SessionId = {
+  readonly chatId: number;
+  readonly threadId: number | undefined;
+};
+
+export type SessionSettings = HostSettings & {
+  readonly logsMode?: LogsMode;
+  readonly temporary?: boolean;
+};
+
+export type SessionDeps = {
+  readonly id: SessionId;
+  readonly settings: SessionSettings;
+  readonly config: TelegramConfig;
+  readonly api: Api;
+  /** Pi's installation, shared with every other surface in this process. */
+  readonly runtime: AgentRuntime;
+  readonly scheduler: TaskScheduler;
+  readonly persistSettings: (patch: Partial<SessionSettings>) => Promise<void>;
+  readonly getBotUsername: () => string | undefined;
+};
+
+const MAIN = "main";
+
+function stamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/** Telegram's chat-scoped adapter over the frontend-agnostic `SessionHost`. */
+export class Session {
+  public readonly id: SessionId;
+  private readonly deps: SessionDeps;
+  private readonly host: SessionHost;
+  private chatSettings: Pick<SessionSettings, "logsMode" | "temporary">;
+
+  public constructor(deps: SessionDeps) {
+    this.deps = deps;
+    this.id = deps.id;
+    this.chatSettings = {
+      logsMode: deps.settings.logsMode,
+      temporary: deps.settings.temporary,
+    };
+    this.host = new SessionHost({
+      label: `session ${encodeId(deps.id)}`,
+      settings: deps.settings,
+      defaults: { cwd: deps.config.cwd, model: deps.config.model },
+      agentDir: deps.runtime.agentDir,
+      modelRuntime: deps.runtime.modelRuntime,
+      modelRegistry: deps.runtime.modelRegistry,
+      settingsManagerFor: (cwd) => deps.runtime.settingsManagerFor(cwd),
+      persistSettings: deps.persistSettings,
+      // Nothing else opens these files; the lease is here for the turn a crashed
+      // daemon left behind, and for an eviction that races its own turn.
+      lease: "daemon",
+      mainSessionPath: () => this.sessionPath("sessions"),
+      isolatedSessionPath: () =>
+        this.sessionPath("isolated-sessions", `-${stamp()}`),
+      systemInstruction: () => this.getSystemInstruction(),
+      customTools: ({ cwd }) => [
+        Tools.wrap(
+          SendFileTool.build({ api: deps.api, sessionId: deps.id, cwd })
+        ),
+        Tools.wrap(
+          TaskTool.build({ scheduler: deps.scheduler, sessionId: deps.id })
+        ),
+      ],
+      onRetire: (path) => this.archive(path),
+    });
+  }
+
+  public get settings(): SessionSettings {
+    return { ...this.host.settings, ...this.chatSettings };
+  }
+
+  public get lastUsed(): number {
+    return this.host.lastUsed;
+  }
+
+  public set lastUsed(value: number) {
+    this.host.lastUsed = value;
+  }
+
+  public get cwd(): string {
+    return this.host.cwd;
+  }
+
+  public get isStreaming(): boolean {
+    return this.host.isStreaming;
+  }
+
+  public usage(): ReturnType<SessionHost["usage"]> {
+    return this.host.usage();
+  }
+
+  public sessionCost(): number | undefined {
+    return this.host.sessionCost();
+  }
+
+  /** Pi's session UUID, once an agent exists. */
+  public get sessionId(): string | undefined {
+    return this.host.sessionId;
+  }
+
+  public get currentModelId(): string | undefined {
+    return this.host.currentModelId;
+  }
+
+  public get supportedThinkingLevels(): readonly ThinkingLevelOpt[] {
+    return this.host.supportedThinkingLevels as readonly ThinkingLevelOpt[];
+  }
+
+  public get currentThinkingLevel(): ThinkingLevelOpt {
+    return this.host.currentThinkingLevel as ThinkingLevelOpt;
+  }
+
+  public get temporary(): boolean {
+    return this.chatSettings.temporary ?? false;
+  }
+
+  public run(
+    work: (agent: AgentSession) => Promise<void>,
+    opts?: { readonly isolated?: boolean }
+  ): Promise<void> {
+    return this.host.run(work, opts);
+  }
+
+  public async cancel(): Promise<boolean> {
+    return (await this.host.cancel()).cancelled;
+  }
+
+  public clear(): Promise<void> {
+    return this.host.clear();
+  }
+
+  public setCwd(newCwd: string): Promise<SetCwdResult> {
+    return this.host.setCwd(newCwd);
+  }
+
+  public setModel(pattern: string): Promise<SetModelResult> {
+    return this.host.setModel(pattern);
+  }
+
+  public setThinkingLevel(level: ThinkingLevelOpt): Promise<void> {
+    return this.host.setThinkingLevel(level as ThinkingLevel);
+  }
+
+  public compact(customInstructions?: string): Promise<SessionCompactResult> {
+    return this.host.compact(customInstructions);
+  }
+
+  public setLogsMode(mode: LogsMode): Promise<void> {
+    return this.host.serialize(async () => {
+      if (this.chatSettings.logsMode === mode) {
+        return;
+      }
+      this.chatSettings = { ...this.chatSettings, logsMode: mode };
+      await this.deps.persistSettings({ logsMode: mode });
+    });
+  }
+
+  public setTemporary(value: boolean): Promise<void> {
+    return this.host.serialize(async () => {
+      if (this.chatSettings.temporary === value) {
+        return;
+      }
+      this.chatSettings = { ...this.chatSettings, temporary: value };
+      await this.deps.persistSettings({ temporary: value });
+    });
+  }
+
+  public dispose(): Promise<void> {
+    return this.host.dispose();
+  }
+
+  private sessionPath(dir: string, suffix = ""): string {
+    return join(
+      this.deps.config.configDir,
+      dir,
+      `${encodeId(this.id)}${suffix}.jsonl`
+    );
+  }
+
+  private async archive(path: string): Promise<void> {
+    try {
+      await rename(path, `${path}.archived-${stamp()}`);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        console.warn(`[session ${encodeId(this.id)}] archive ${path}:`, err);
+      }
+    }
+  }
+
+  private async getSystemInstruction(): Promise<string | undefined> {
+    const path = join(
+      this.deps.config.configDir,
+      "instructions",
+      `${encodeId(this.id)}.md`
+    );
+    let userContent: string | undefined;
+    try {
+      userContent = (await Bun.file(path).text()).trim();
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        console.warn(
+          `[telegram-user-instruction] failed to read ${path}:`,
+          err
+        );
+      }
+    }
+    const username = this.deps.getBotUsername();
+    const handle = username ? ` (@${username})` : "";
+    const systemIx = `You are running as a Telegram bot${handle} powered by Pim Agent. The telegram_user_instructions below are your editable instructions - edit the file at its \`path\` attribute to update your instructions. Wrap LaTeX math in a \`\`\`math fenced block without the $$ delimitters; inline math is not supported.`;
+    const userIx = `<telegram_user_instructions path="${path}">${userContent ? `\n${userContent}\n` : ""}</telegram_user_instructions>`;
+    return `<telegram_system_instructions>\n${systemIx}\n${userIx}\n</telegram_system_instructions>`;
+  }
+}
+
+export function encodeId(id: SessionId): string {
+  return `${id.chatId}-${id.threadId ?? MAIN}`;
+}
+
+export function decodeId(s: string): SessionId {
+  const idx = s.lastIndexOf("-");
+  const chatId = Number(s.slice(0, idx));
+  const tail = s.slice(idx + 1);
+  return {
+    chatId,
+    threadId: tail === MAIN ? undefined : Number(tail),
+  };
+}

package/packages/telegram/src/SessionRegistry.ts

@@ -0,0 +1,126 @@
+import type { Api } from "grammy";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import { AgentRuntime } from "#core/session/AgentRuntime";
+import { SessionCache } from "#core/session/SessionCache";
+import { Fs } from "#core/shared/Fs";
+import { type TelegramConfig } from "./Config";
+import {
+  encodeId,
+  Session,
+  type SessionId,
+  type SessionSettings,
+} from "./Session";
+import type { TaskScheduler } from "./TaskScheduler";
+
+export class SessionRegistry {
+  private readonly config: TelegramConfig;
+  private readonly api: Api;
+  private readonly scheduler: TaskScheduler;
+  private readonly runtime: AgentRuntime;
+  private readonly cache = new SessionCache<Session>();
+  private settings: Map<string, SessionSettings> = new Map();
+  private initialized = false;
+  private initPromise: Promise<void> | undefined;
+  private botUsername: string | undefined;
+
+  public constructor(
+    config: TelegramConfig,
+    api: Api,
+    scheduler: TaskScheduler,
+    runtime: AgentRuntime
+  ) {
+    this.config = config;
+    this.api = api;
+    this.scheduler = scheduler;
+    this.runtime = runtime;
+  }
+
+  public setBotUsername(username: string): void {
+    this.botUsername = username;
+  }
+
+  public async init(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+    this.initPromise ??= this.bootstrap().catch((err: unknown) => {
+      this.initPromise = undefined;
+      throw err;
+    });
+    await this.initPromise;
+  }
+
+  public get(sessionId: SessionId): Session {
+    this.requireInitialized();
+    const key = encodeId(sessionId);
+    const cached = this.cache.touch(key);
+    if (cached) {
+      return cached;
+    }
+    return this.cache.adopt(
+      key,
+      new Session({
+        id: sessionId,
+        settings: this.settings.get(key) ?? {},
+        config: this.config,
+        api: this.api,
+        runtime: this.runtime,
+        scheduler: this.scheduler,
+        persistSettings: (patch) => this.persistSettings(key, patch),
+        getBotUsername: () => this.botUsername,
+      })
+    );
+  }
+
+  public async disposeAll(): Promise<void> {
+    await this.cache.disposeAll();
+    if (this.initialized) {
+      await this.flushSettings();
+    }
+  }
+
+  private async bootstrap(): Promise<void> {
+    await this.runtime.init();
+    const loaded = await Fs.readJsonOrEmpty<Record<string, SessionSettings>>(
+      join(this.config.configDir, "state.json"),
+      {}
+    );
+    this.settings = new Map(Object.entries(loaded));
+    await mkdir(join(this.config.configDir, "sessions"), { recursive: true });
+    await mkdir(join(this.config.configDir, "isolated-sessions"), {
+      recursive: true,
+    });
+    await mkdir(join(this.config.configDir, "instructions"), {
+      recursive: true,
+    });
+    this.initialized = true;
+  }
+
+  private requireInitialized(): void {
+    if (!this.initialized) {
+      throw new Error("SessionRegistry.init() must complete before use");
+    }
+  }
+
+  private async persistSettings(
+    key: string,
+    patch: Partial<SessionSettings>
+  ): Promise<void> {
+    const prev = this.settings.get(key) ?? {};
+    this.settings.set(key, { ...prev, ...patch });
+    await this.flushSettings();
+  }
+
+  private async flushSettings(): Promise<void> {
+    try {
+      await Fs.writeAtomic(
+        join(this.config.configDir, "state.json"),
+        JSON.stringify(Object.fromEntries(this.settings), null, 2)
+      );
+    } catch (err) {
+      console.warn(`[registry] state save failed:`, err);
+    }
+  }
+}

package/packages/telegram/src/TaskScheduler.ts

@@ -0,0 +1,296 @@
+import type { SessionId } from "./Session";
+import type { ScheduleSpec, ScheduledTask } from "./TaskSchema";
+import { TaskStore } from "./TaskStore";
+
+export type RunTaskFn = (task: ScheduledTask) => Promise<void>;
+
+export type TaskSchedulerOptions = {
+  readonly configDir: string;
+  readonly runTask: RunTaskFn;
+  readonly pollIntervalMs?: number;
+  readonly now?: () => number;
+};
+
+const MISSED_TASK_WINDOW_MS = 24 * 3600_000;
+const MIN_INTERVAL_MS = 60_000;
+
+export class TaskScheduler {
+  private readonly configDir: string;
+  private readonly runTask: RunTaskFn;
+  private readonly pollIntervalMs: number;
+  private readonly now: () => number;
+  private timer: Timer | undefined;
+  private inflight: Promise<void> | undefined;
+
+  public constructor(opts: TaskSchedulerOptions) {
+    this.configDir = opts.configDir;
+    this.runTask = opts.runTask;
+    this.pollIntervalMs = opts.pollIntervalMs ?? 10_000;
+    this.now = opts.now ?? ((): number => Date.now());
+  }
+
+  public async start(): Promise<void> {
+    if (this.timer) {
+      return;
+    }
+    this.timer = setInterval(() => {
+      void this.tick();
+    }, this.pollIntervalMs);
+    await this.tick();
+  }
+
+  public async stop(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    if (this.inflight) {
+      await this.inflight;
+    }
+  }
+
+  public async tick(): Promise<void> {
+    if (this.inflight) {
+      await this.inflight;
+      return;
+    }
+    const run = this.runTick().finally(() => {
+      this.inflight = undefined;
+    });
+    this.inflight = run;
+    await run;
+  }
+
+  public async list(
+    sessionId: SessionId
+  ): Promise<ReadonlyArray<ScheduledTask>> {
+    const all = await TaskStore.loadAll(this.configDir);
+    return all
+      .filter(
+        (t) =>
+          t.chatId === sessionId.chatId && t.threadId === sessionId.threadId
+      )
+      .sort((a, b) => a.nextRun.localeCompare(b.nextRun));
+  }
+
+  public async create(
+    sessionId: SessionId,
+    input: {
+      readonly prompt: string;
+      readonly schedule: ScheduleSpec;
+      readonly expires?: string;
+      readonly isolatedSession?: boolean;
+    }
+  ): Promise<ScheduledTask> {
+    const nextRun = this.computeFirstRun(input.schedule);
+    if (input.expires !== undefined) {
+      const expMs = Date.parse(input.expires);
+      if (!Number.isFinite(expMs)) {
+        throw new Error(`invalid expires timestamp: ${input.expires}`);
+      }
+      if (expMs <= Date.parse(nextRun)) {
+        throw new Error(
+          `expires must be strictly after first nextRun (${nextRun})`
+        );
+      }
+    }
+    const task: ScheduledTask = {
+      id: TaskStore.makeId(input.prompt),
+      prompt: input.prompt,
+      chatId: sessionId.chatId,
+      threadId: sessionId.threadId,
+      schedule: input.schedule,
+      status: "active",
+      nextRun,
+      expires: input.expires ?? null,
+      isolatedSession: input.isolatedSession ?? false,
+      createdAt: new Date(this.now()).toISOString(),
+    };
+    await TaskStore.save(this.configDir, task);
+    return task;
+  }
+
+  public async delete(sessionId: SessionId, id: string): Promise<boolean> {
+    const t = await this.find(sessionId, id);
+    if (!t) {
+      return false;
+    }
+    await TaskStore.remove(this.configDir, id);
+    return true;
+  }
+
+  public setStatus(
+    sessionId: SessionId,
+    id: string,
+    status: "active" | "paused"
+  ): Promise<ScheduledTask | undefined> {
+    return this.mutate(sessionId, id, (t) =>
+      t.status === status ? undefined : { ...t, status }
+    );
+  }
+
+  public updatePrompt(
+    sessionId: SessionId,
+    id: string,
+    prompt: string
+  ): Promise<ScheduledTask | undefined> {
+    return this.mutate(sessionId, id, (t) =>
+      t.prompt === prompt ? undefined : { ...t, prompt }
+    );
+  }
+
+  private async mutate(
+    sessionId: SessionId,
+    id: string,
+    patch: (task: ScheduledTask) => ScheduledTask | undefined
+  ): Promise<ScheduledTask | undefined> {
+    const t = await this.find(sessionId, id);
+    if (!t) {
+      return undefined;
+    }
+    const updated = patch(t);
+    if (!updated) {
+      return t;
+    }
+    await TaskStore.save(this.configDir, updated);
+    return updated;
+  }
+
+  private async find(
+    sessionId: SessionId,
+    id: string
+  ): Promise<ScheduledTask | undefined> {
+    const all = await this.list(sessionId);
+    return all.find((t) => t.id === id);
+  }
+
+  private async runTick(): Promise<void> {
+    const all = await TaskStore.loadAll(this.configDir);
+    const now = this.now();
+    const fires: Promise<void>[] = [];
+
+    for (const task of all) {
+      if (task.status !== "active") {
+        continue;
+      }
+      const nextMs = Date.parse(task.nextRun);
+      if (!Number.isFinite(nextMs) || nextMs > now) {
+        continue;
+      }
+
+      if (task.expires) {
+        const expMs = Date.parse(task.expires);
+        if (Number.isFinite(expMs) && now > expMs) {
+          await TaskStore.remove(this.configDir, task.id);
+          continue;
+        }
+      }
+
+      if (now - nextMs > MISSED_TASK_WINDOW_MS) {
+        const advanced = advanceNextRun(task, now);
+        if (advanced) {
+          await TaskStore.save(this.configDir, advanced);
+        } else {
+          await TaskStore.remove(this.configDir, task.id);
+        }
+        console.warn(
+          `[scheduler] task ${task.id} missed by >24h, advanced silently`
+        );
+        continue;
+      }
+
+      fires.push(this.fireAndReschedule(task, now));
+    }
+
+    await Promise.allSettled(fires);
+  }
+
+  private async fireAndReschedule(
+    task: ScheduledTask,
+    firedAt: number
+  ): Promise<void> {
+    try {
+      await this.runTask(task);
+    } catch (err) {
+      console.error(`[scheduler] task ${task.id} runTask failed:`, err);
+    }
+    const next = advanceNextRun(task, firedAt);
+    if (next) {
+      await TaskStore.save(this.configDir, next);
+    } else {
+      await TaskStore.remove(this.configDir, task.id);
+    }
+  }
+
+  private computeFirstRun(schedule: ScheduleSpec): string {
+    const now = this.now();
+    if (schedule.type === "once") {
+      const at = Date.parse(schedule.at);
+      if (!Number.isFinite(at)) {
+        throw new Error(`invalid 'at' timestamp: ${schedule.at}`);
+      }
+      if (at <= now) {
+        throw new Error(`'at' must be strictly in the future`);
+      }
+      return new Date(at).toISOString();
+    }
+    if (schedule.type === "interval") {
+      const ms = parseDuration(schedule.every);
+      if (ms < MIN_INTERVAL_MS) {
+        throw new Error(`interval must be at least 1 minute`);
+      }
+      return new Date(now + ms).toISOString();
+    }
+    const next = Bun.cron.parse(schedule.expr, new Date(now));
+    if (!next) {
+      throw new Error(`cron expression has no future match: ${schedule.expr}`);
+    }
+    return next.toISOString();
+  }
+}
+
+function advanceNextRun(
+  task: ScheduledTask,
+  fromMs: number
+): ScheduledTask | undefined {
+  const schedule = task.schedule;
+  if (schedule.type === "once") {
+    return undefined;
+  }
+  if (schedule.type === "interval") {
+    const ms = parseDuration(schedule.every);
+    return { ...task, nextRun: new Date(fromMs + ms).toISOString() };
+  }
+  const next = Bun.cron.parse(schedule.expr, new Date(fromMs));
+  if (!next) {
+    return undefined;
+  }
+  return { ...task, nextRun: next.toISOString() };
+}
+
+export function parseDuration(input: string): number {
+  const s = input.trim();
+  if (!s) {
+    throw new Error("empty duration");
+  }
+  let remaining = s;
+  let total = 0;
+  while (remaining.length > 0) {
+    const m = remaining.match(/^(\d+)([smhd])/);
+    if (!m) {
+      throw new Error(`bad duration: ${input}`);
+    }
+    const n = Number(m[1]);
+    const mult = DURATION_UNITS[m[2]!]!;
+    total += n * mult;
+    remaining = remaining.slice(m[0].length);
+  }
+  return total;
+}
+
+const DURATION_UNITS: Record<string, number> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};