@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-telegram/lib/ownership.ts

@@ -0,0 +1,298 @@
+/**
+ * Telegram message ownership helpers
+ * Zones: telegram routing, multi-instance bus, in-memory coordination
+ * Owns live message-id ownership lookup so callbacks/reactions can resolve a Telegram UI surface back to the instance/target that produced it
+ */
+
+import { getTelegramTargetKey, type TelegramTarget } from "./target.ts";
+
+export interface TelegramMessageOwnershipRecord {
+  chatId: number;
+  messageId: number;
+  target: TelegramTarget;
+  instanceId: string;
+  profileKey?: string;
+  ownerGeneration?: string;
+  recipientBindingKey?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface TelegramMessageOwnershipStore {
+  record: (input: {
+    chatId: number;
+    messageId: number;
+    target?: TelegramTarget;
+    instanceId: string;
+    profileKey?: string;
+    ownerGeneration?: string;
+    recipientBindingKey?: string;
+    now?: number;
+  }) => TelegramMessageOwnershipRecord;
+  get: (
+    chatId: number,
+    messageId: number,
+  ) => TelegramMessageOwnershipRecord | undefined;
+  forget: (chatId: number, messageId: number) => boolean;
+  forgetTarget: (target: TelegramTarget) => number;
+  prune: (options: {
+    now: number;
+    maxAgeMs?: number;
+    maxRecords?: number;
+  }) => number;
+  entries: () => TelegramMessageOwnershipRecord[];
+  clear: () => void;
+}
+
+export interface TelegramFollowerOwnershipView {
+  instanceId: string;
+  connectedAtMs: number;
+  profileKey?: string;
+  registrationGeneration?: string;
+}
+
+export interface TelegramBusMessageOwnershipRuntime {
+  store: TelegramMessageOwnershipStore;
+  recordLocal(input: {
+    chatId: number;
+    messageId: number;
+    target?: TelegramTarget;
+  }): TelegramMessageOwnershipRecord;
+  recordRouted(input: {
+    chatId: number;
+    messageId: number;
+    target?: TelegramTarget;
+    instanceId: string;
+  }): TelegramMessageOwnershipRecord;
+  recordFollower(input: {
+    chatId: number;
+    messageId: number;
+    target?: TelegramTarget;
+    follower: TelegramFollowerOwnershipView;
+  }): TelegramMessageOwnershipRecord;
+  isOwnedByFollower(input: {
+    chatId: number;
+    messageId: number;
+    follower: TelegramFollowerOwnershipView;
+  }): boolean;
+}
+
+function getTelegramFollowerOwnershipGeneration(
+  follower: TelegramFollowerOwnershipView,
+): string {
+  return (
+    follower.registrationGeneration ??
+    `${follower.instanceId}:${follower.connectedAtMs}`
+  );
+}
+
+export function createTelegramBusMessageOwnershipRuntime(deps: {
+  instanceId: string;
+  getProfileKey(): string;
+  listFollowers(): readonly TelegramFollowerOwnershipView[];
+}): TelegramBusMessageOwnershipRuntime {
+  const store = createTelegramMessageOwnershipStore({
+    getProfileKey: deps.getProfileKey,
+    isOwnerGenerationLive(record) {
+      if (!record.ownerGeneration) return true;
+      return deps.listFollowers().some((follower) => {
+        return (
+          follower.instanceId === record.instanceId &&
+          getTelegramFollowerOwnershipGeneration(follower) ===
+            record.ownerGeneration
+        );
+      });
+    },
+    resolveOwnerReplacement(record) {
+      if (!record.recipientBindingKey) return undefined;
+      const follower = deps
+        .listFollowers()
+        .find(
+          (candidate) =>
+            candidate.profileKey === record.recipientBindingKey,
+        );
+      return follower
+        ? {
+            instanceId: follower.instanceId,
+            ownerGeneration: getTelegramFollowerOwnershipGeneration(follower),
+            recipientBindingKey: record.recipientBindingKey,
+          }
+        : undefined;
+    },
+  });
+  const recordFollower = function (input: {
+    chatId: number;
+    messageId: number;
+    target?: TelegramTarget;
+    follower: TelegramFollowerOwnershipView;
+  }): TelegramMessageOwnershipRecord {
+    return store.record({
+      chatId: input.chatId,
+      messageId: input.messageId,
+      target: input.target,
+      instanceId: input.follower.instanceId,
+      ownerGeneration: getTelegramFollowerOwnershipGeneration(input.follower),
+      recipientBindingKey: input.follower.profileKey,
+    });
+  };
+  return {
+    store,
+    recordLocal(input) {
+      return store.record({ ...input, instanceId: deps.instanceId });
+    },
+    recordRouted(input) {
+      const follower = deps
+        .listFollowers()
+        .find((candidate) => candidate.instanceId === input.instanceId);
+      return follower
+        ? recordFollower({ ...input, follower })
+        : store.record(input);
+    },
+    recordFollower,
+    isOwnedByFollower({ chatId, messageId, follower }) {
+      const ownership = store.get(chatId, messageId);
+      return (
+        ownership?.instanceId === follower.instanceId &&
+        ownership.ownerGeneration ===
+          getTelegramFollowerOwnershipGeneration(follower)
+      );
+    },
+  };
+}
+
+function getTelegramMessageOwnershipKey(
+  chatId: number,
+  messageId: number,
+  profileKey?: string,
+): string {
+  return `${profileKey ?? ""}:${chatId}:${messageId}`;
+}
+
+function createTelegramMessageOwnershipRecord(input: {
+  chatId: number;
+  messageId: number;
+  target?: TelegramTarget;
+  instanceId: string;
+  profileKey?: string;
+  ownerGeneration?: string;
+  recipientBindingKey?: string;
+  now: number;
+  previous?: TelegramMessageOwnershipRecord;
+}): TelegramMessageOwnershipRecord {
+  return {
+    chatId: input.chatId,
+    messageId: input.messageId,
+    target: input.target ?? { chatId: input.chatId },
+    instanceId: input.instanceId,
+    ...(input.profileKey ? { profileKey: input.profileKey } : {}),
+    ...(input.ownerGeneration
+      ? { ownerGeneration: input.ownerGeneration }
+      : {}),
+    ...(input.recipientBindingKey
+      ? { recipientBindingKey: input.recipientBindingKey }
+      : {}),
+    createdAt: input.previous?.createdAt ?? input.now,
+    updatedAt: input.now,
+  };
+}
+
+export function createTelegramMessageOwnershipStore(
+  options: {
+    getProfileKey?: () => string | undefined;
+    isOwnerGenerationLive?: (record: TelegramMessageOwnershipRecord) => boolean;
+    resolveOwnerReplacement?: (
+      record: TelegramMessageOwnershipRecord,
+    ) =>
+      | Pick<
+          TelegramMessageOwnershipRecord,
+          "instanceId" | "ownerGeneration" | "recipientBindingKey"
+        >
+      | undefined;
+  } = {},
+): TelegramMessageOwnershipStore {
+  const records = new Map<string, TelegramMessageOwnershipRecord>();
+  return {
+    record: (input) => {
+      const profileKey = input.profileKey ?? options.getProfileKey?.();
+      const key = getTelegramMessageOwnershipKey(
+        input.chatId,
+        input.messageId,
+        profileKey,
+      );
+      const now = input.now ?? Date.now();
+      const record = createTelegramMessageOwnershipRecord({
+        ...input,
+        profileKey,
+        now,
+        previous: records.get(key),
+      });
+      records.set(key, record);
+      return record;
+    },
+    get: (chatId, messageId) => {
+      const key = getTelegramMessageOwnershipKey(
+        chatId,
+        messageId,
+        options.getProfileKey?.(),
+      );
+      const record = records.get(key);
+      if (!record) return undefined;
+      if (
+        record.ownerGeneration &&
+        options.isOwnerGenerationLive &&
+        !options.isOwnerGenerationLive(record)
+      ) {
+        const replacement = options.resolveOwnerReplacement?.(record);
+        if (!replacement) return undefined;
+        const rebound = { ...record, ...replacement };
+        records.set(key, rebound);
+        return rebound;
+      }
+      return record;
+    },
+    forget: (chatId, messageId) =>
+      records.delete(
+        getTelegramMessageOwnershipKey(
+          chatId,
+          messageId,
+          options.getProfileKey?.(),
+        ),
+      ),
+    forgetTarget: (target) => {
+      const targetKey = getTelegramTargetKey(target);
+      const profileKey = options.getProfileKey?.();
+      let removed = 0;
+      for (const [key, record] of records) {
+        if ((record.profileKey ?? undefined) !== profileKey) continue;
+        if (getTelegramTargetKey(record.target) !== targetKey) continue;
+        records.delete(key);
+        removed += 1;
+      }
+      return removed;
+    },
+    prune: ({ now, maxAgeMs, maxRecords }) => {
+      let removed = 0;
+      if (maxAgeMs !== undefined) {
+        for (const [key, record] of records) {
+          if (now - record.updatedAt <= maxAgeMs) continue;
+          records.delete(key);
+          removed += 1;
+        }
+      }
+      if (maxRecords !== undefined && records.size > maxRecords) {
+        const oldest = [...records.entries()].sort(
+          (left, right) => left[1].updatedAt - right[1].updatedAt,
+        );
+        for (const [key] of oldest.slice(0, records.size - maxRecords)) {
+          records.delete(key);
+          removed += 1;
+        }
+      }
+      return removed;
+    },
+    entries: () => [...records.values()],
+    clear: () => {
+      records.clear();
+    },
+  };
+}

package/node_modules/@llblab/pi-telegram/lib/paths.ts

@@ -0,0 +1,127 @@
+/**
+ * Telegram bridge path resolution for Pi-compatible runtimes
+ * Zones: telemetry paths, filesystem, runtime identity
+ * Owns agent-dir detection and extension-local path derivation
+ *
+ * This domain is pure/path-only: it resolves directories and file paths
+ * from environment and runtime identity. It does not read config, manage
+ * state, or import broader Telegram domains.
+ */
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const TELEGRAM_DEFAULT_PROFILE_NAME = "default";
+
+export interface TelegramAgentDirResolutionInput {
+  env?: Partial<Pick<NodeJS.ProcessEnv, "PI_CODING_AGENT_DIR">>;
+  execPath?: string;
+  argv?: readonly string[];
+}
+
+/**
+ * Resolve the agent data directory for the current Pi-compatible runtime.
+ *
+ * Precedence:
+ * 1. `PI_CODING_AGENT_DIR` env variable, when explicitly set.
+ * 2. Detect Pi-compatible runtime identity from the executable or argv[1]
+ *    (e.g. OMP vs standard Pi agent).
+ * 3. Fallback: `~/.pi/agent`.
+ */
+export function resolveAgentDir(
+  input: TelegramAgentDirResolutionInput = {},
+): string {
+  const env = input.env ?? process.env;
+  if (env.PI_CODING_AGENT_DIR) return resolve(env.PI_CODING_AGENT_DIR);
+  const execPath = input.execPath ?? process.execPath;
+  const argv = input.argv ?? process.argv;
+  const execBasename = execPath.toLowerCase().split(/[\\/]/u).pop() ?? "";
+  const argv1Last = (argv[1] ?? "").toLowerCase().split(/[\\/]/u).pop() ?? "";
+  if (execBasename.startsWith("omp") || argv1Last.startsWith("omp")) {
+    return join(homedir(), ".omp", "agent");
+  }
+  return join(homedir(), ".pi", "agent");
+}
+
+/** Telegram bridge configuration file (<agentDir>/telegram.json). */
+export function resolveTelegramConfigPath(): string {
+  return join(resolveAgentDir(), "telegram.json");
+}
+
+/** Telegram bridge temporary directory (<agentDir>/tmp/telegram). */
+export function resolveTelegramTempDir(agentDir = resolveAgentDir()): string {
+  return join(agentDir, "tmp", "telegram");
+}
+
+/** Telegram transport ownership store (<agentDir>/tmp/telegram/owners.json). */
+export function resolveTelegramOwnersPath(): string {
+  return join(resolveTelegramTempDir(), "owners.json");
+}
+
+export function getTelegramProfilePathSuffix(profileName?: string): string {
+  if (!profileName || profileName === TELEGRAM_DEFAULT_PROFILE_NAME) return "";
+  return `.${profileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}`;
+}
+
+export function resolveTelegramProfileTempFilePath(
+  baseName: string,
+  extension: string,
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return join(
+    resolveTelegramTempDir(agentDir),
+    `${baseName}${getTelegramProfilePathSuffix(profileName)}.${extension}`,
+  );
+}
+
+export function getTelegramDiagnosticsDisplayPaths(profileName?: string): {
+  state: string;
+  logs: string;
+} {
+  const suffix = getTelegramProfilePathSuffix(profileName);
+  const profileSlug = suffix.slice(1);
+  return {
+    state: `~/.pi/agent/tmp/telegram/state${suffix}.json`,
+    logs: `~/.pi/agent/tmp/telegram/logs${profileSlug ? `.${profileSlug}` : ""}.jsonl`,
+  };
+}
+
+/** Durable inbound update journal (<agentDir>/tmp/telegram/inbox[.<profile>].json). */
+export function resolveTelegramUpdateJournalPath(
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return resolveTelegramProfileTempFilePath(
+    "inbox",
+    "json",
+    agentDir,
+    profileName,
+  );
+}
+
+/** Durable follower delivery journal, isolated by stable recipient binding. */
+export function resolveTelegramFollowerJournalPath(
+  recipientBindingKey: string,
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  if (!recipientBindingKey) {
+    throw new Error("Telegram follower journal binding key is required.");
+  }
+  const bindingHash = createHash("sha256")
+    .update(recipientBindingKey)
+    .digest("hex")
+    .slice(0, 16);
+  return resolveTelegramProfileTempFilePath(
+    `follower-inbox-${bindingHash}`,
+    "json",
+    agentDir,
+    profileName,
+  );
+}
+
+/** Runtime event log (<agentDir>/tmp/telegram/logs.jsonl). */
+export function resolveTelegramRuntimeLogPath(): string {
+  return resolveTelegramProfileTempFilePath("logs", "jsonl");
+}

package/node_modules/@llblab/pi-telegram/lib/pi.ts

@@ -0,0 +1,197 @@
+/**
+ * pi SDK adapter boundary
+ * Zones: pi agent sdk boundary, shared adapters
+ * Owns direct pi SDK imports and exposes narrow bridge-facing helpers/types for the extension composition layer
+ */
+
+import type { AssistantMessageEvent } from "@earendil-works/pi-ai";
+import {
+  type AgentEndEvent,
+  type AgentSettledEvent,
+  type AgentStartEvent,
+  type BeforeAgentStartEvent,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+  type ExtensionContext,
+  type InputEvent,
+  type SessionBeforeCompactEvent,
+  type SessionCompactEvent,
+  type SessionShutdownEvent,
+  type SessionStartEvent,
+  type SlashCommandInfo,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+export type {
+  AgentEndEvent,
+  AgentSettledEvent,
+  AgentStartEvent,
+  AssistantMessageEvent,
+  BeforeAgentStartEvent,
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+  InputEvent,
+  SessionBeforeCompactEvent,
+  SessionCompactEvent,
+  SessionShutdownEvent,
+  SessionStartEvent,
+  SlashCommandInfo,
+};
+
+export interface ToolExecutionStartEvent {
+  type: "tool_execution_start";
+  toolCallId: string;
+  toolName: string;
+  args: unknown;
+}
+
+export interface ToolExecutionUpdateEvent {
+  type: "tool_execution_update";
+  toolCallId: string;
+  toolName: string;
+  args: unknown;
+  partialResult: unknown;
+}
+
+export interface ToolExecutionEndEvent {
+  type: "tool_execution_end";
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+  isError: boolean;
+}
+
+export interface PiSettingsManager {
+  reload: () => Promise<void>;
+  flush: () => Promise<void>;
+  getEnabledModels: () => string[] | undefined;
+  setEnabledModels: (patterns: string[] | undefined) => void;
+}
+
+export type PiSlashCommandInfo = SlashCommandInfo;
+export type PiRunMode = "tui" | "rpc" | "json" | "print";
+
+function isPiRunMode(value: unknown): value is PiRunMode {
+  return (
+    value === "tui" || value === "rpc" || value === "json" || value === "print"
+  );
+}
+
+export function getExtensionContextMode(ctx: unknown): PiRunMode | undefined {
+  const mode =
+    typeof ctx === "object" && ctx !== null
+      ? (ctx as { mode?: unknown }).mode
+      : undefined;
+  return isPiRunMode(mode) ? mode : undefined;
+}
+
+export function isExtensionContextPassiveRunMode(ctx: unknown): boolean {
+  const mode = getExtensionContextMode(ctx);
+  return mode === "print" || mode === "json";
+}
+
+export function canStartPollingInExtensionContext(ctx: unknown): boolean {
+  return !isExtensionContextPassiveRunMode(ctx);
+}
+
+export function formatPollingStartBlockedByRunMode(ctx: unknown): string {
+  const mode = getExtensionContextMode(ctx);
+  return mode
+    ? `Telegram polling is unavailable in Pi ${mode} mode. Use /telegram-connect from a long-lived Pi session.`
+    : "Telegram polling is unavailable in this Pi run mode.";
+}
+
+export function getSessionCompactionReason(
+  event: unknown,
+): "manual" | "threshold" | "overflow" | "unknown" {
+  const reason =
+    event && typeof event === "object" && "reason" in event
+      ? (event as { reason?: unknown }).reason
+      : undefined;
+  return reason === "manual" || reason === "threshold" || reason === "overflow"
+    ? reason
+    : "unknown";
+}
+
+export interface PiExtensionApiRuntimePorts {
+  sendUserMessage: ExtensionAPI["sendUserMessage"];
+  exec: ExtensionAPI["exec"];
+  getCommands: ExtensionAPI["getCommands"];
+  getThinkingLevel: ExtensionAPI["getThinkingLevel"];
+  setThinkingLevel: ExtensionAPI["setThinkingLevel"];
+  getActiveTools: ExtensionAPI["getActiveTools"];
+  setActiveTools: ExtensionAPI["setActiveTools"];
+  setModel: ExtensionAPI["setModel"];
+}
+
+export function createExtensionApiRuntimePorts(
+  api: Pick<
+    ExtensionAPI,
+    | "sendUserMessage"
+    | "exec"
+    | "getCommands"
+    | "getThinkingLevel"
+    | "setThinkingLevel"
+    | "getActiveTools"
+    | "setActiveTools"
+    | "setModel"
+  >,
+): PiExtensionApiRuntimePorts {
+  return {
+    sendUserMessage: (content, options) =>
+      api.sendUserMessage(content, options),
+    exec: (command, args, options) => api.exec(command, args, options),
+    getCommands: () => api.getCommands(),
+    getThinkingLevel: () => api.getThinkingLevel(),
+    setThinkingLevel: (level) => api.setThinkingLevel(level),
+    getActiveTools: () => api.getActiveTools(),
+    setActiveTools: (names) => api.setActiveTools(names),
+    setModel: (model) => api.setModel(model),
+  };
+}
+
+export function createSettingsManager(cwd: string): PiSettingsManager {
+  return SettingsManager.create(cwd);
+}
+
+export function createScopedModelPatternPersister(deps: {
+  createSettingsManager: (cwd: string) => PiSettingsManager;
+  clearCachedModelMenuInputs: () => void;
+}): (patterns: string[], ctx: ExtensionContext) => Promise<void> {
+  return async (patterns, ctx) => {
+    const settingsManager = deps.createSettingsManager(ctx.cwd);
+    settingsManager.setEnabledModels(
+      patterns.length > 0 ? patterns : undefined,
+    );
+    await settingsManager.flush();
+    deps.clearCachedModelMenuInputs();
+  };
+}
+
+export function getExtensionContextModel(
+  ctx: ExtensionContext,
+): ExtensionContext["model"] {
+  return ctx.model;
+}
+
+export function getExtensionContextCwd(ctx: ExtensionContext): string {
+  return ctx.cwd;
+}
+
+export function isExtensionContextIdle(ctx: ExtensionContext): boolean {
+  return ctx.isIdle();
+}
+
+export function hasExtensionContextPendingMessages(
+  ctx: ExtensionContext,
+): boolean {
+  return ctx.hasPendingMessages();
+}
+
+export function compactExtensionContext(
+  ctx: ExtensionContext,
+  callbacks: Parameters<ExtensionContext["compact"]>[0],
+): ReturnType<ExtensionContext["compact"]> {
+  return ctx.compact(callbacks);
+}