@llblab/pi-telegram 0.46.0 → 0.48.0

package/dist/lib/ownership.js

@@ -0,0 +1,174 @@
+/**
+ * Telegram message ownership helpers
+ * Zones: telegram routing, multi-instance bus, in-memory coordination
+ * Owns message-id ownership and live forwarding projections so inbound updates resolve back to the instance/target that owns them
+ */
+import { TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION, } from "./bus.js";
+import { getTelegramTargetKey } from "./target.js";
+function getTelegramFollowerOwnershipGeneration(follower) {
+    return (follower.registrationGeneration ??
+        `${follower.instanceId}:${follower.connectedAtMs}`);
+}
+export function createTelegramBusMessageOwnershipRuntime(deps) {
+    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) {
+        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,
+        getForwardOwnership(chatId, messageId) {
+            const record = store.get(chatId, messageId);
+            if (!record?.ownerGeneration || !record.recipientBindingKey)
+                return record;
+            const follower = deps.listFollowers().find((candidate) => candidate.instanceId === record.instanceId &&
+                candidate.registrationGeneration === record.ownerGeneration &&
+                candidate.profileKey === record.recipientBindingKey);
+            // Protocol is live registration authority, not message-cache history.
+            // Keep an incomplete known owner foreign so the forwarder fails closed.
+            return follower?.protocol?.capabilities.includes(TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION) ? { ...record, protocolIdentity: follower.protocol } : record;
+        },
+        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, messageId, profileKey) {
+    return `${profileKey ?? ""}:${chatId}:${messageId}`;
+}
+function createTelegramMessageOwnershipRecord(input) {
+    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 = {}) {
+    const records = new Map();
+    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/dist/lib/paths.d.ts

@@ -0,0 +1,40 @@
+export declare 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 declare function resolveAgentDir(input?: TelegramAgentDirResolutionInput): string;
+/** Telegram bridge configuration file (<agentDir>/telegram.json). */
+export declare function resolveTelegramConfigPath(): string;
+/** Telegram bridge temporary directory (<agentDir>/tmp/telegram). */
+export declare function resolveTelegramTempDir(agentDir?: string): string;
+/** Telegram transport ownership store (<agentDir>/tmp/telegram/owners.json). */
+export declare function resolveTelegramOwnersPath(): string;
+export declare function getTelegramProfilePathSuffix(profileName?: string): string;
+export declare function resolveTelegramProfileTempFilePath(baseName: string, extension: string, agentDir?: string, profileName?: string): string;
+export declare function getTelegramDiagnosticsDisplayPaths(profileName?: string): {
+    state: string;
+    logs: string;
+};
+/** Durable Workspace admission ledger (<agentDir>/tmp/telegram/workspace-admission[.<profile>].json). */
+export declare function resolveTelegramWorkspaceAdmissionPath(agentDir?: string, profileName?: string): string;
+/** Durable inactive Thread cleanup work-set journal. */
+export declare function resolveTelegramThreadCleanupWorkPath(agentDir?: string, profileName?: string): string;
+/** Durable agent-authored channel post journal. */
+export declare function resolveTelegramChannelPostJournalPath(agentDir?: string, profileName?: string): string;
+/** Durable inbound update journal (<agentDir>/tmp/telegram/inbox[.<profile>].json). */
+export declare function resolveTelegramUpdateJournalPath(agentDir?: string, profileName?: string): string;
+/** Durable follower delivery journal, isolated by stable recipient binding. */
+export declare function resolveTelegramFollowerJournalPath(recipientBindingKey: string, agentDir?: string, profileName?: string): string;
+/** Runtime event log (<agentDir>/tmp/telegram/logs.jsonl). */
+export declare function resolveTelegramRuntimeLogPath(): string;

package/dist/lib/paths.js

@@ -0,0 +1,94 @@
+/**
+ * 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";
+/**
+ * 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 = {}) {
+    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() {
+    return join(resolveAgentDir(), "telegram.json");
+}
+/** Telegram bridge temporary directory (<agentDir>/tmp/telegram). */
+export function resolveTelegramTempDir(agentDir = resolveAgentDir()) {
+    return join(agentDir, "tmp", "telegram");
+}
+/** Telegram transport ownership store (<agentDir>/tmp/telegram/owners.json). */
+export function resolveTelegramOwnersPath() {
+    return join(resolveTelegramTempDir(), "owners.json");
+}
+export function getTelegramProfilePathSuffix(profileName) {
+    if (!profileName || profileName === TELEGRAM_DEFAULT_PROFILE_NAME)
+        return "";
+    return `.${profileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}`;
+}
+export function resolveTelegramProfileTempFilePath(baseName, extension, agentDir = resolveAgentDir(), profileName) {
+    return join(resolveTelegramTempDir(agentDir), `${baseName}${getTelegramProfilePathSuffix(profileName)}.${extension}`);
+}
+export function getTelegramDiagnosticsDisplayPaths(profileName) {
+    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 Workspace admission ledger (<agentDir>/tmp/telegram/workspace-admission[.<profile>].json). */
+export function resolveTelegramWorkspaceAdmissionPath(agentDir = resolveAgentDir(), profileName) {
+    return resolveTelegramProfileTempFilePath("workspace-admission", "json", agentDir, profileName);
+}
+/** Durable inactive Thread cleanup work-set journal. */
+export function resolveTelegramThreadCleanupWorkPath(agentDir = resolveAgentDir(), profileName) {
+    return resolveTelegramProfileTempFilePath("thread-cleanup", "json", agentDir, profileName);
+}
+/** Durable agent-authored channel post journal. */
+export function resolveTelegramChannelPostJournalPath(agentDir = resolveAgentDir(), profileName) {
+    return resolveTelegramProfileTempFilePath("channel-posts", "json", agentDir, profileName);
+}
+/** Durable inbound update journal (<agentDir>/tmp/telegram/inbox[.<profile>].json). */
+export function resolveTelegramUpdateJournalPath(agentDir = resolveAgentDir(), profileName) {
+    return resolveTelegramProfileTempFilePath("inbox", "json", agentDir, profileName);
+}
+/** Durable follower delivery journal, isolated by stable recipient binding. */
+export function resolveTelegramFollowerJournalPath(recipientBindingKey, agentDir = resolveAgentDir(), profileName) {
+    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() {
+    return resolveTelegramProfileTempFilePath("logs", "jsonl");
+}

package/dist/lib/pi.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 MessageEndEvent, type SessionBeforeCompactEvent, type SessionCompactEvent, type SessionShutdownEvent, type SessionStartEvent, type SlashCommandInfo, type UIPromptEndEvent, type UIPromptStartEvent } from "@earendil-works/pi-coding-agent";
+export type { AgentEndEvent, AgentSettledEvent, AgentStartEvent, AssistantMessageEvent, BeforeAgentStartEvent, ExtensionAPI, ExtensionCommandContext, ExtensionContext, InputEvent, MessageEndEvent, SessionBeforeCompactEvent, SessionCompactEvent, SessionShutdownEvent, SessionStartEvent, SlashCommandInfo, UIPromptEndEvent, UIPromptStartEvent, };
+export interface SessionCompactFailedEvent {
+    type: "session_compact_failed";
+    reason: "manual" | "threshold" | "overflow";
+    errorMessage?: string;
+    aborted: boolean;
+    willRetry: boolean;
+    fromExtension: boolean;
+}
+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";
+export declare function getExtensionContextMode(ctx: unknown): PiRunMode | undefined;
+export declare function isExtensionContextPassiveRunMode(ctx: unknown): boolean;
+export declare function canStartPollingInExtensionContext(ctx: unknown): boolean;
+export declare function formatPollingStartBlockedByRunMode(ctx: unknown): string;
+export declare function getSessionCompactionReason(event: unknown): "manual" | "threshold" | "overflow" | "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 declare function createExtensionApiRuntimePorts(api: Pick<ExtensionAPI, "sendUserMessage" | "exec" | "getCommands" | "getThinkingLevel" | "setThinkingLevel" | "getActiveTools" | "setActiveTools" | "setModel">): PiExtensionApiRuntimePorts;
+export declare function normalizeSettingsManager(manager: unknown): PiSettingsManager;
+export declare function createSettingsManager(cwd: string): Promise<PiSettingsManager>;
+export declare function createScopedModelPatternPersister(deps: {
+    createSettingsManager: (cwd: string) => PiSettingsManager | PromiseLike<PiSettingsManager>;
+    clearCachedModelMenuInputs: () => void;
+}): (patterns: string[], ctx: ExtensionContext) => Promise<void>;
+export declare function getExtensionContextModel(ctx: ExtensionContext): ExtensionContext["model"];
+export declare function getExtensionContextCwd(ctx: ExtensionContext): string;
+export declare function getExtensionContextSessionId(ctx: ExtensionContext): string;
+export declare function isExtensionContextIdle(ctx: ExtensionContext): boolean;
+export declare function hasExtensionContextPendingMessages(ctx: ExtensionContext): boolean;
+export declare function compactExtensionContext(ctx: ExtensionContext, callbacks: Parameters<ExtensionContext["compact"]>[0]): ReturnType<ExtensionContext["compact"]>;

package/dist/lib/pi.js

@@ -0,0 +1,121 @@
+/**
+ * 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 { SettingsManager, } from "@earendil-works/pi-coding-agent";
+function isPiRunMode(value) {
+    return (value === "tui" || value === "rpc" || value === "json" || value === "print");
+}
+export function getExtensionContextMode(ctx) {
+    const mode = typeof ctx === "object" && ctx !== null
+        ? ctx.mode
+        : undefined;
+    return isPiRunMode(mode) ? mode : undefined;
+}
+export function isExtensionContextPassiveRunMode(ctx) {
+    const mode = getExtensionContextMode(ctx);
+    return mode === "print" || mode === "json";
+}
+export function canStartPollingInExtensionContext(ctx) {
+    return !isExtensionContextPassiveRunMode(ctx);
+}
+export function formatPollingStartBlockedByRunMode(ctx) {
+    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) {
+    const reason = event && typeof event === "object" && "reason" in event
+        ? event.reason
+        : undefined;
+    return reason === "manual" || reason === "threshold" || reason === "overflow"
+        ? reason
+        : "unknown";
+}
+export function createExtensionApiRuntimePorts(api) {
+    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),
+    };
+}
+function readEnabledModels(value) {
+    if (value === undefined)
+        return undefined;
+    if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+        return [...value];
+    }
+    throw new TypeError("Host settings enabledModels must be a string array or undefined.");
+}
+export function normalizeSettingsManager(manager) {
+    if (typeof manager !== "object" || manager === null) {
+        throw new TypeError("Host settings manager must be an object.");
+    }
+    const host = manager;
+    if (typeof host.flush !== "function") {
+        throw new TypeError("Host settings manager must provide flush().");
+    }
+    const read = typeof host.getEnabledModels === "function"
+        ? () => host.getEnabledModels.call(host)
+        : typeof host.get === "function"
+            ? () => host.get.call(host, "enabledModels")
+            : undefined;
+    const write = typeof host.setEnabledModels === "function"
+        ? (patterns) => host.setEnabledModels.call(host, patterns)
+        : typeof host.set === "function"
+            ? (patterns) => host.set.call(host, "enabledModels", patterns ?? [])
+            : undefined;
+    if (!read || !write) {
+        throw new TypeError("Host settings manager must provide enabled-model read and write capabilities.");
+    }
+    return {
+        reload: async () => {
+            await host.reload?.call(host);
+        },
+        flush: async () => {
+            await host.flush.call(host);
+        },
+        getEnabledModels: () => readEnabledModels(read()),
+        setEnabledModels: write,
+    };
+}
+export async function createSettingsManager(cwd) {
+    // Pi returns its legacy settings surface synchronously. Compatible hosts may
+    // resolve a generic settings service asynchronously; normalize both once at
+    // the SDK boundary instead of leaking host distinctions into menu domains.
+    const factory = SettingsManager;
+    return normalizeSettingsManager(await factory.create(cwd));
+}
+export function createScopedModelPatternPersister(deps) {
+    return async (patterns, ctx) => {
+        const settingsManager = await deps.createSettingsManager(ctx.cwd);
+        settingsManager.setEnabledModels(patterns.length > 0 ? patterns : undefined);
+        await settingsManager.flush();
+        deps.clearCachedModelMenuInputs();
+    };
+}
+export function getExtensionContextModel(ctx) {
+    return ctx.model;
+}
+export function getExtensionContextCwd(ctx) {
+    return ctx.cwd;
+}
+export function getExtensionContextSessionId(ctx) {
+    return ctx.sessionManager.getSessionId();
+}
+export function isExtensionContextIdle(ctx) {
+    return ctx.isIdle();
+}
+export function hasExtensionContextPendingMessages(ctx) {
+    return ctx.hasPendingMessages();
+}
+export function compactExtensionContext(ctx, callbacks) {
+    return ctx.compact(callbacks);
+}