pi-control-bridge 0.3.10

package/extension/session_metadata.ts

@@ -0,0 +1,84 @@
+import { basename } from "node:path";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const DESCRIPTION_MAX_LEN = 240;
+
+function truncate(text: string, maxLen: number): string {
+  const trimmed = text.trim();
+  if (trimmed.length <= maxLen) return trimmed;
+  return `${trimmed.slice(0, maxLen - 1)}…`;
+}
+
+function extractTextContent(content: unknown): string | undefined {
+  if (typeof content === "string") {
+    const trimmed = content.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+  if (!Array.isArray(content)) return undefined;
+
+  const parts: string[] = [];
+  for (const item of content) {
+    if (typeof item === "string") {
+      const trimmed = item.trim();
+      if (trimmed) parts.push(trimmed);
+      continue;
+    }
+    if (item && typeof item === "object") {
+      const block = item as { type?: string; text?: string };
+      if (block.type === "text" && typeof block.text === "string") {
+        const trimmed = block.text.trim();
+        if (trimmed) parts.push(trimmed);
+      }
+    }
+  }
+  if (parts.length === 0) return undefined;
+  return parts.join("\n");
+}
+
+function extractUserMessageText(message: unknown): string | undefined {
+  if (!message || typeof message !== "object") return undefined;
+  const candidate = message as { role?: string; content?: unknown };
+  if (candidate.role !== "user") return undefined;
+  return extractTextContent(candidate.content);
+}
+
+export function extractFirstUserPrompt(ctx: ExtensionContext): string | undefined {
+  for (const entry of ctx.sessionManager.getEntries()) {
+    if (entry.type !== "message") continue;
+    const text = extractUserMessageText(entry.message);
+    if (text) return truncate(text, DESCRIPTION_MAX_LEN);
+  }
+  return undefined;
+}
+
+export function extractLatestUserPromptFromMessages(messages: unknown[]): string | undefined {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const text = extractUserMessageText(messages[index]);
+    if (text) return truncate(text, DESCRIPTION_MAX_LEN);
+  }
+  return undefined;
+}
+
+export function buildSessionMetadata(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  options?: { messages?: unknown[] },
+): Record<string, string> {
+  const metadata: Record<string, string> = {};
+
+  const title = pi.getSessionName()?.trim();
+  if (title) metadata.title = title;
+
+  const description =
+    (options?.messages ? extractLatestUserPromptFromMessages(options.messages) : undefined) ??
+    extractFirstUserPrompt(ctx);
+  if (description) metadata.description = description;
+
+  const projectBasename = basename(ctx.cwd);
+  if (projectBasename) metadata.projectBasename = projectBasename;
+
+  metadata.mode = ctx.mode;
+
+  return metadata;
+}

package/extension/session_status.ts

@@ -0,0 +1,19 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type SessionStatus = "waiting_user" | "running";
+
+/** Session start and other idle/busy boundaries where isIdle() reflects UI state. */
+export function sessionStatusFromContext(ctx: Pick<ExtensionContext, "isIdle">): SessionStatus {
+  return ctx.isIdle() ? "waiting_user" : "running";
+}
+
+/**
+ * Status after a user prompt completes (agent_end).
+ * Pi may still report isStreaming=true inside agent_end handlers, so use the
+ * pending message queue instead: no queued steer/follow-up means waiting for user.
+ */
+export function sessionStatusAfterAgentEnd(
+  ctx: Pick<ExtensionContext, "hasPendingMessages">,
+): SessionStatus {
+  return ctx.hasPendingMessages() ? "running" : "waiting_user";
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "pi-control-bridge",
+  "version": "0.3.10",
+  "description": "Pi agent bridge extension and singleton runtime for pi-control-hub integration.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "bridge",
+    "control-hub"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.14.1",
+    "hono": "^4.7.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "esbuild": "^0.25.1",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "bin": {
+    "pi-bridge": "./dist/bridge/main.js"
+  },
+  "files": [
+    "dist/bridge/main.js",
+    "extension/",
+    "shared/",
+    "bridge.config.example.json",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extension/index.ts"
+    ]
+  },
+  "scripts": {
+    "build": "esbuild bridge/main.ts --bundle --platform=node --format=esm --outfile=dist/bridge/main.js --banner:js=\"#!/usr/bin/env node\"",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "check": "tsc --noEmit"
+  }
+}

package/shared/agent_dir.ts

@@ -0,0 +1,17 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/** Pi agent config directory (default `~/.pi/agent`, overridable via `PI_CODING_AGENT_DIR`). */
+export function getAgentDir(): string {
+  const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+  if (!configured) {
+    return join(homedir(), ".pi", "agent");
+  }
+  if (configured === "~") {
+    return homedir();
+  }
+  if (configured.startsWith("~/")) {
+    return resolve(homedir(), configured.slice(2));
+  }
+  return resolve(configured);
+}

package/shared/ansi.ts

@@ -0,0 +1,9 @@
+const RESET = "\x1b[0m";
+
+export const ansi = {
+  reset: RESET,
+  title: (text: string) => `\x1b[1;96m${text}${RESET}`,
+  label: (text: string) => `\x1b[97m${text}${RESET}`,
+  link: (text: string) => `\x1b[94;4m${text}${RESET}`,
+  accent: (text: string) => `\x1b[93m${text}${RESET}`,
+};

package/shared/config.ts

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { getAgentDir } from "./agent_dir.ts";
+import {
+  DEFAULT_HUB_URL,
+  DEFAULT_BRIDGE_LOG_LEVEL,
+  DEFAULT_COMMAND_BATCH_SIZE,
+  DEFAULT_HEARTBEAT_INTERVAL_SEC,
+  DEFAULT_IPC_PORT,
+  DEFAULT_POLL_INTERVAL_SEC,
+  PROJECT_CONFIG_RELATIVE_PATH,
+} from "./constants.ts";
+import { defaultBridgeDataDir, migrateLegacyBridgePaths } from "./migrate.ts";
+import type { BridgeConfig, BridgeConfigFile } from "./types.ts";
+
+function expandHome(path: string): string {
+  return path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+}
+
+function positiveNumber(value: unknown, fallback: number): number {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return fallback;
+}
+
+function defaultConfig(): BridgeConfig {
+  return {
+    hubUrl: DEFAULT_HUB_URL,
+    pollIntervalSec: DEFAULT_POLL_INTERVAL_SEC,
+    heartbeatIntervalSec: DEFAULT_HEARTBEAT_INTERVAL_SEC,
+    commandBatchSize: DEFAULT_COMMAND_BATCH_SIZE,
+    bridgeLogLevel: DEFAULT_BRIDGE_LOG_LEVEL,
+    bridgeDataDir: defaultBridgeDataDir(),
+    ipcPort: DEFAULT_IPC_PORT,
+    autoStartBridge: true,
+  };
+}
+
+function readConfigFile(path: string): BridgeConfigFile | null {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as BridgeConfigFile;
+  } catch {
+    return null;
+  }
+}
+
+function applyConfigFile(base: BridgeConfig, file: BridgeConfigFile): BridgeConfig {
+  return {
+    hubUrl:
+      typeof file.hub_url === "string" && file.hub_url.trim()
+        ? file.hub_url.trim()
+        : base.hubUrl,
+    pollIntervalSec: positiveNumber(file.poll_interval_sec, base.pollIntervalSec),
+    heartbeatIntervalSec: positiveNumber(
+      file.heartbeat_interval_sec,
+      base.heartbeatIntervalSec,
+    ),
+    commandBatchSize: positiveNumber(file.command_batch_size, base.commandBatchSize),
+    bridgeLogLevel:
+      typeof file.bridge_log_level === "string" && file.bridge_log_level.trim()
+        ? file.bridge_log_level.trim()
+        : base.bridgeLogLevel,
+    bridgeDataDir:
+      typeof file.bridge_data_dir === "string" && file.bridge_data_dir.trim()
+        ? expandHome(file.bridge_data_dir.trim())
+        : base.bridgeDataDir,
+    ipcPort: positiveNumber(file.ipc_port, base.ipcPort),
+    autoStartBridge:
+      typeof file.auto_start_bridge === "boolean"
+        ? file.auto_start_bridge
+        : base.autoStartBridge,
+  };
+}
+
+export function userConfigPath(): string {
+  return join(getAgentDir(), "bridge", "config.json");
+}
+
+/** Walk up from startDir and return the nearest project bridge config path. */
+export function findProjectConfigPath(startDir: string = process.cwd()): string | null {
+  let current = startDir;
+  while (true) {
+    const candidate = join(current, PROJECT_CONFIG_RELATIVE_PATH);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export interface LoadBridgeConfigOptions {
+  /** Project directory used to locate `.pi/bridge.json` (walks up from here). */
+  cwd?: string;
+  /** Override project config path (tests). Pass `null` to skip project config. */
+  projectConfigPath?: string | null;
+  /** Override user config path (tests). Pass `null` to skip user config. */
+  userConfigPath?: string | null;
+  /** Skip legacy path migration (tests). */
+  skipMigration?: boolean;
+}
+
+/**
+ * Load bridge config. Priority (low → high):
+ * 1. defaults
+ * 2. `~/.pi/agent/bridge/config.json`
+ * 3. `.pi/bridge.json` in project (nearest ancestor of cwd)
+ */
+export function loadBridgeConfig(options: LoadBridgeConfigOptions = {}): BridgeConfig {
+  if (!options.skipMigration) {
+    migrateLegacyBridgePaths();
+  }
+
+  let config = defaultConfig();
+
+  const userPath =
+    options.userConfigPath === null
+      ? null
+      : (options.userConfigPath ?? userConfigPath());
+  if (userPath) {
+    const userFile = readConfigFile(userPath);
+    if (userFile) config = applyConfigFile(config, userFile);
+  }
+
+  const projectPath =
+    options.projectConfigPath === null
+      ? null
+      : (options.projectConfigPath ?? findProjectConfigPath(options.cwd));
+  if (projectPath) {
+    const projectFile = readConfigFile(projectPath);
+    if (projectFile) config = applyConfigFile(config, projectFile);
+  }
+
+  return config;
+}
+
+export function ipcBaseUrl(port: number): string {
+  return `http://127.0.0.1:${port}`;
+}
+
+export function stateFilePath(dataDir: string): string {
+  return join(dataDir, "state.json");
+}
+
+export function eventsQueuePath(dataDir: string): string {
+  return join(dataDir, "events-queue.jsonl");
+}

package/shared/constants.ts

@@ -0,0 +1,13 @@
+export const PACKAGE_VERSION = "0.3.3";
+
+export const DEFAULT_HUB_URL = "http://127.0.0.1:8000";
+export const DEFAULT_POLL_INTERVAL_SEC = 2;
+export const DEFAULT_HEARTBEAT_INTERVAL_SEC = 15;
+export const DEFAULT_COMMAND_BATCH_SIZE = 10;
+export const DEFAULT_BRIDGE_LOG_LEVEL = "INFO";
+export const DEFAULT_IPC_PORT = 9473;
+export const PROJECT_CONFIG_RELATIVE_PATH = ".pi/bridge.json";
+
+export const IPC_COMMAND_WAIT_TIMEOUT_MS = 30_000;
+export const COMMAND_RETRY_ATTEMPTS = 3;
+export const COMMAND_RETRY_DELAY_MS = 2_000;

package/shared/device_state.ts

@@ -0,0 +1,21 @@
+import type { DeviceState } from "./types.ts";
+
+/** Whether the bridge should call GET /me to probe Telegram link state. */
+export function shouldProbeTelegramLink(state: DeviceState | null | undefined): boolean {
+  if (!state?.deviceToken) return false;
+  return state.telegramBindPending === true || state.telegramLinked === true;
+}
+
+export function hasDeviceCredentials(state: DeviceState | null | undefined): boolean {
+  return Boolean(state?.deviceToken);
+}
+
+export function clearDeviceCredentials(state: DeviceState): DeviceState {
+  return {
+    ...state,
+    deviceId: "",
+    deviceToken: "",
+    telegramLinked: false,
+    telegramBindPending: false,
+  };
+}

package/shared/locale.ts

@@ -0,0 +1,30 @@
+export type AppLocale = "ru" | "en";
+
+export function getSystemLocale(): AppLocale {
+  const candidates = [
+    process.env.LC_ALL,
+    process.env.LC_MESSAGES,
+    process.env.LANG,
+    Intl.DateTimeFormat().resolvedOptions().locale,
+  ];
+
+  for (const raw of candidates) {
+    if (!raw) continue;
+    const normalized = raw.replace(/\.utf-8$/i, "").replace(/_/g, "-").toLowerCase();
+    if (normalized.startsWith("ru")) return "ru";
+  }
+
+  return "en";
+}
+
+export function pluralMinutes(count: number, locale: AppLocale): string {
+  if (locale === "en") {
+    return count === 1 ? "minute" : "minutes";
+  }
+
+  const mod10 = count % 10;
+  const mod100 = count % 100;
+  if (mod10 === 1 && mod100 !== 11) return "минуту";
+  if (mod10 >= 2 && mod10 <= 4 && (mod100 < 10 || mod100 >= 20)) return "минуты";
+  return "минут";
+}

package/shared/logger.ts

@@ -0,0 +1,54 @@
+type LogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  DEBUG: 10,
+  INFO: 20,
+  WARN: 30,
+  ERROR: 40,
+};
+
+export interface LogContext {
+  deviceId?: string;
+  externalSessionId?: string;
+  hubSessionId?: string;
+  commandId?: string;
+  eventId?: string;
+  correlationId?: string;
+  [key: string]: unknown;
+}
+
+export class Logger {
+  private readonly minLevel: number;
+
+  constructor(level: string) {
+    const normalized = level.toUpperCase() as LogLevel;
+    this.minLevel = LEVEL_ORDER[normalized] ?? LEVEL_ORDER.INFO;
+  }
+
+  private write(level: LogLevel, message: string, context?: LogContext): void {
+    if (LEVEL_ORDER[level] < this.minLevel) return;
+    const entry = {
+      ts: new Date().toISOString(),
+      level,
+      message,
+      ...context,
+    };
+    console.error(JSON.stringify(entry));
+  }
+
+  debug(message: string, context?: LogContext): void {
+    this.write("DEBUG", message, context);
+  }
+
+  info(message: string, context?: LogContext): void {
+    this.write("INFO", message, context);
+  }
+
+  warn(message: string, context?: LogContext): void {
+    this.write("WARN", message, context);
+  }
+
+  error(message: string, context?: LogContext): void {
+    this.write("ERROR", message, context);
+  }
+}

package/shared/migrate.ts

@@ -0,0 +1,39 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { getAgentDir } from "./agent_dir.ts";
+
+export function legacyBridgeDataDir(): string {
+  return join(homedir(), ".pi", "bridge");
+}
+
+export function defaultBridgeDataDir(): string {
+  return join(getAgentDir(), "bridge");
+}
+
+/** Move `~/.pi/bridge` → `~/.pi/agent/bridge` when the new location is still empty. */
+export function migrateLegacyBridgePaths(): void {
+  const oldDir = legacyBridgeDataDir();
+  const newDir = defaultBridgeDataDir();
+  if (oldDir === newDir || !existsSync(oldDir)) return;
+
+  if (!existsSync(newDir)) {
+    mkdirSync(getAgentDir(), { recursive: true });
+    try {
+      renameSync(oldDir, newDir);
+      return;
+    } catch {
+      // Fall through to per-file copy if rename fails (e.g. cross-device).
+    }
+  }
+
+  mkdirSync(newDir, { recursive: true, mode: 0o700 });
+  for (const name of readdirSync(oldDir)) {
+    const source = join(oldDir, name);
+    const target = join(newDir, name);
+    if (!existsSync(target)) {
+      copyFileSync(source, target);
+    }
+  }
+}

package/shared/telegram.ts

@@ -0,0 +1,136 @@
+export interface TelegramLinkResponse {
+  token: string;
+  expiresAt: string;
+  botUsername?: string;
+  botLink?: string;
+  alreadyLinked?: boolean;
+  telegramUsername?: string;
+}
+
+export interface HubTelegramConnection {
+  linked: boolean;
+  username?: string;
+  chatId?: number;
+}
+
+export interface HubBotInfo {
+  username?: string;
+  link?: string;
+}
+
+export interface HubConnectionInfo {
+  deviceId?: string;
+  telegram: HubTelegramConnection;
+  bot: HubBotInfo;
+}
+
+export function buildTelegramBotLink(botUsername: string, token?: string): string {
+  const username = botUsername.replace(/^@/, "");
+  const base = `https://t.me/${username}`;
+  if (!token) return base;
+  return `${base}?start=${encodeURIComponent(token)}`;
+}
+
+export function buildAlreadyLinkedTelegramResponse(connection: HubConnectionInfo): TelegramLinkResponse {
+  return {
+    token: "",
+    expiresAt: "",
+    alreadyLinked: true,
+    botUsername: connection.bot.username,
+    botLink: connection.bot.link,
+    telegramUsername: connection.telegram.username,
+  };
+}
+
+export function parseTelegramLinkResponse(raw: Record<string, unknown>): TelegramLinkResponse {
+  const alreadyLinked = raw.already_linked === true || raw.alreadyLinked === true;
+  const token = String(raw.token ?? "");
+  const expiresAt = String(raw.expires_at ?? raw.expiresAt ?? "");
+  const telegramUsernameRaw = raw.telegram_username ?? raw.telegramUsername;
+  const telegramUsername =
+    typeof telegramUsernameRaw === "string" && telegramUsernameRaw.length > 0
+      ? telegramUsernameRaw
+      : undefined;
+  const botUsernameRaw = raw.bot_username ?? raw.botUsername;
+  const botUsername =
+    typeof botUsernameRaw === "string" && botUsernameRaw.length > 0
+      ? botUsernameRaw
+      : undefined;
+  const botLinkRaw = raw.bot_link ?? raw.botLink;
+  const botLink =
+    typeof botLinkRaw === "string" && botLinkRaw.length > 0
+      ? botLinkRaw
+      : botUsername
+        ? buildTelegramBotLink(botUsername, token)
+        : undefined;
+
+  return { token, expiresAt, botUsername, botLink, alreadyLinked, telegramUsername };
+}
+
+function readTelegramBlock(raw: Record<string, unknown>): Record<string, unknown> | undefined {
+  const telegram = raw.telegram;
+  return telegram && typeof telegram === "object" ? (telegram as Record<string, unknown>) : undefined;
+}
+
+function readBotBlock(raw: Record<string, unknown>): Record<string, unknown> | undefined {
+  const bot = raw.bot;
+  return bot && typeof bot === "object" ? (bot as Record<string, unknown>) : undefined;
+}
+
+export function parseHubConnectionInfo(raw: Record<string, unknown>): HubConnectionInfo {
+  const telegramBlock = readTelegramBlock(raw);
+  const botBlock = readBotBlock(raw);
+
+  const linked =
+    telegramBlock?.linked === true ||
+    raw.telegram_linked === true ||
+    raw.telegramLinked === true;
+
+  const telegramUsernameRaw =
+    telegramBlock?.username ?? raw.telegram_username ?? raw.telegramUsername;
+  const telegramUsername =
+    typeof telegramUsernameRaw === "string" && telegramUsernameRaw.length > 0
+      ? telegramUsernameRaw
+      : undefined;
+
+  const chatIdRaw = telegramBlock?.chat_id ?? telegramBlock?.chatId ?? raw.telegram_chat_id;
+  const chatId =
+    typeof chatIdRaw === "number"
+      ? chatIdRaw
+      : typeof chatIdRaw === "string" && chatIdRaw.length > 0
+        ? Number(chatIdRaw)
+        : undefined;
+
+  const botUsernameRaw =
+    botBlock?.username ?? raw.bot_username ?? raw.botUsername;
+  const botUsername =
+    typeof botUsernameRaw === "string" && botUsernameRaw.length > 0
+      ? botUsernameRaw
+      : undefined;
+
+  const botLinkRaw = botBlock?.link ?? raw.bot_link ?? raw.botLink;
+  const botLink =
+    typeof botLinkRaw === "string" && botLinkRaw.length > 0
+      ? botLinkRaw
+      : botUsername
+        ? buildTelegramBotLink(botUsername)
+        : undefined;
+
+  return {
+    deviceId:
+      typeof raw.device_id === "string"
+        ? raw.device_id
+        : typeof raw.deviceId === "string"
+          ? raw.deviceId
+          : undefined,
+    telegram: {
+      linked,
+      username: telegramUsername,
+      chatId: Number.isFinite(chatId) ? chatId : undefined,
+    },
+    bot: {
+      username: botUsername,
+      link: botLink,
+    },
+  };
+}