@brain0pia/pi-notify 0.1.0 → 0.2.0

package/README.md

@@ -25,6 +25,27 @@ Create `~/.pi/notify.json`:
 }
 ```
 
+Optional: add a session URL template. If present, `SESSION_ID` is replaced with the current Pi session id and the resolved link is included in each Telegram notification.
+
+```json
+{
+  "botToken": "123456:ABCDEF...",
+  "chatId": "123456789",
+  "sessionUrlTemplate": "https://session-viewer.example/#SESSION_ID"
+}
+```
+
+You can also manage that field from Pi with the slash command:
+
+```text
+/pi-notify-url https://session-viewer.example/#SESSION_ID
+```
+
+Useful variants:
+
+- `/pi-notify-url` — show the current template
+- `/pi-notify-url off` — clear the template
+
 ## Behavior
 
 After every `agent_end` event the extension:
@@ -35,7 +56,7 @@ After every `agent_end` event the extension:
 4. Cancels on any other key.
 5. Sends automatically when the countdown reaches zero.
 
-The Telegram payload includes metadata (`project`, `cwd`, `timestamp`, `model`) plus the full assistant output. Short outputs are sent as a MarkdownV2 message with a plain-text fallback on parse errors. Long outputs are sent as a short header message plus a `.md` attachment containing the full response.
+The Telegram payload includes metadata (`project`, `cwd`, `timestamp`, `model`) plus the full assistant output. If `sessionUrlTemplate` is configured, the notification also includes an `Open session` link built from the current session id. Short outputs are sent as a MarkdownV2 message with a plain-text fallback on parse errors. Long outputs are sent as a short header message plus a `.md` attachment containing the full response.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brain0pia/pi-notify",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pi package that sends Telegram notifications after each completed agent response.",
   "type": "module",
   "keywords": [

package/src/config.ts

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 
@@ -6,20 +6,93 @@ import type { ConfigLoadResult } from "./types.js";
 
 export const NOTIFY_CONFIG_PATH = path.join(homedir(), ".pi", "notify.json");
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function normalizeSessionUrlTemplate(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function resolveSessionUrl(template: string | undefined, sessionId: string): string | undefined {
+  const normalizedTemplate = normalizeSessionUrlTemplate(template);
+  const normalizedSessionId = sessionId.trim();
+  if (!normalizedTemplate || !normalizedSessionId) {
+    return undefined;
+  }
+
+  return normalizedTemplate.replaceAll("SESSION_ID", normalizedSessionId);
+}
+
+async function readNotifyConfigRecord(configPath = NOTIFY_CONFIG_PATH): Promise<Record<string, unknown>> {
+  let raw: string;
+
+  try {
+    raw = await readFile(configPath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return {};
+    }
+
+    throw error;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`pi-notify: invalid JSON in ${configPath}: ${message}`);
+  }
+
+  if (!isRecord(parsed)) {
+    throw new Error(`pi-notify: expected an object in ${configPath}.`);
+  }
+
+  return { ...parsed };
+}
+
+export async function getNotifySessionUrlTemplate(configPath = NOTIFY_CONFIG_PATH): Promise<string | undefined> {
+  const record = await readNotifyConfigRecord(configPath);
+  return normalizeSessionUrlTemplate(record.sessionUrlTemplate);
+}
+
+export async function setNotifySessionUrlTemplate(
+  template: string | undefined,
+  configPath = NOTIFY_CONFIG_PATH,
+): Promise<void> {
+  const record = await readNotifyConfigRecord(configPath);
+  const normalizedTemplate = normalizeSessionUrlTemplate(template);
+
+  if (normalizedTemplate) {
+    record.sessionUrlTemplate = normalizedTemplate;
+  } else {
+    delete record.sessionUrlTemplate;
+  }
+
+  await mkdir(path.dirname(configPath), { recursive: true });
+  await writeFile(configPath, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+}
+
 export function validateNotifyConfig(value: unknown, configPath = NOTIFY_CONFIG_PATH): ConfigLoadResult {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
+  if (!isRecord(value)) {
     return { ok: false, reason: `pi-notify: expected an object in ${configPath}.` };
   }
 
-  const record = value as Record<string, unknown>;
-  const botToken = typeof record.botToken === "string" ? record.botToken.trim() : "";
-  const chatIdValue = record.chatId;
+  const botToken = typeof value.botToken === "string" ? value.botToken.trim() : "";
+  const chatIdValue = value.chatId;
   const chatId =
     typeof chatIdValue === "string"
       ? chatIdValue.trim()
       : typeof chatIdValue === "number" && Number.isFinite(chatIdValue)
         ? String(chatIdValue)
         : "";
+  const sessionUrlTemplate = normalizeSessionUrlTemplate(value.sessionUrlTemplate);
 
   if (!botToken) {
     return { ok: false, reason: `pi-notify: missing \"botToken\" in ${configPath}.` };
@@ -38,6 +111,7 @@ export function validateNotifyConfig(value: unknown, configPath = NOTIFY_CONFIG_
     config: {
       botToken,
       chatId,
+      ...(sessionUrlTemplate ? { sessionUrlTemplate } : {}),
     },
   };
 }

package/src/controller.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 
-import { loadNotifyConfig } from "./config.js";
+import { loadNotifyConfig, resolveSessionUrl } from "./config.js";
 import { showCountdownOverlay, type CountdownOverlayOptions } from "./countdown.js";
 import { sendTelegramNotification } from "./telegram.js";
 import type { ConfigLoadResult, CountdownDecision, NotificationPayload, NotifyConfig } from "./types.js";
@@ -60,7 +60,7 @@ export function extractAssistantText(messages: readonly AgentMessageLike[]): str
 
 export function createNotificationPayload(
   messages: readonly AgentMessageLike[],
-  ctx: Pick<ExtensionContext, "cwd" | "model">,
+  ctx: Pick<ExtensionContext, "cwd" | "model" | "sessionManager">,
   now: Date,
 ): NotificationPayload | null {
   const assistantText = extractAssistantText(messages);
@@ -77,12 +77,28 @@ export function createNotificationPayload(
       project: basename.length > 0 ? basename : cwd,
       cwd,
       timestamp: now.toISOString(),
+      sessionId: ctx.sessionManager.getSessionId(),
       model,
     },
     assistantText,
   };
 }
 
+export function applySessionUrlTemplate(payload: NotificationPayload, config: NotifyConfig): NotificationPayload {
+  const sessionUrl = resolveSessionUrl(config.sessionUrlTemplate, payload.metadata.sessionId);
+  if (!sessionUrl) {
+    return payload;
+  }
+
+  return {
+    ...payload,
+    metadata: {
+      ...payload.metadata,
+      sessionUrl,
+    },
+  };
+}
+
 function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -122,11 +138,12 @@ export class PiNotifyController {
       return;
     }
 
+    const payloadWithSessionUrl = applySessionUrlTemplate(payload, configResult.config);
     this.lastConfigWarning = null;
     const job = this.startNewJob();
 
     if (!ctx.hasUI) {
-      this.scheduleBackgroundSend(job, ctx, configResult.config, payload);
+      this.scheduleBackgroundSend(job, ctx, configResult.config, payloadWithSessionUrl);
       return;
     }
 
@@ -144,7 +161,7 @@ export class PiNotifyController {
 
       this.finishJob(job.id);
       if (decision === "send" || decision === "timeout") {
-        await this.deliver(configResult.config, payload, ctx);
+        await this.deliver(configResult.config, payloadWithSessionUrl, ctx);
       }
     } catch (error) {
       if (!this.isActive(job.id)) {
@@ -152,7 +169,7 @@ export class PiNotifyController {
       }
 
       this.notify(ctx, `pi-notify: overlay unavailable, sending automatically in ${Math.ceil(this.delayMs / 1000)}s.`, "warning");
-      this.scheduleBackgroundSend(job, ctx, configResult.config, payload);
+      this.scheduleBackgroundSend(job, ctx, configResult.config, payloadWithSessionUrl);
       const description = describeError(error);
       if (description) {
         this.notify(ctx, `pi-notify: overlay error: ${description}`, "warning");

package/src/format.ts

@@ -10,7 +10,7 @@ function normalizeAssistantText(text: string): string {
   return normalized.length > 0 ? normalized : EMPTY_ASSISTANT_MESSAGE;
 }
 
-function metadataLines(metadata: NotificationMetadata): string[] {
+function baseMetadataLines(metadata: NotificationMetadata): string[] {
   return [
     `Project: ${metadata.project}`,
     `CWD: ${metadata.cwd}`,
@@ -19,6 +19,33 @@ function metadataLines(metadata: NotificationMetadata): string[] {
   ];
 }
 
+function plainMetadataLines(metadata: NotificationMetadata): string[] {
+  return [
+    ...baseMetadataLines(metadata),
+    ...(metadata.sessionUrl ? [`Session: ${metadata.sessionUrl}`] : []),
+  ];
+}
+
+function escapeMarkdownV2LinkUrl(url: string): string {
+  return url.replace(/\\/g, "\\\\").replace(/\)/g, "\\)");
+}
+
+function markdownSessionLine(metadata: NotificationMetadata): string | undefined {
+  if (!metadata.sessionUrl) {
+    return undefined;
+  }
+
+  return `Session: [Open session](${escapeMarkdownV2LinkUrl(metadata.sessionUrl)})`;
+}
+
+function markdownMetadataLines(metadata: NotificationMetadata): string[] {
+  const sessionLine = markdownSessionLine(metadata);
+  return [
+    ...baseMetadataLines(metadata).map((line) => escapeMarkdownV2(line)),
+    ...(sessionLine ? [sessionLine] : []),
+  ];
+}
+
 export function escapeMarkdownV2(text: string): string {
   return text.replace(MARKDOWN_V2_SPECIALS, (char) => `\\${char}`);
 }
@@ -26,7 +53,7 @@ export function escapeMarkdownV2(text: string): string {
 export function buildPlainTextMessage(payload: NotificationPayload): string {
   return [
     "Pi finished",
-    ...metadataLines(payload.metadata),
+    ...plainMetadataLines(payload.metadata),
     "",
     normalizeAssistantText(payload.assistantText),
   ].join("\n");
@@ -36,7 +63,7 @@ export function buildMarkdownMessage(payload: NotificationPayload): string {
   const assistantText = escapeMarkdownV2(normalizeAssistantText(payload.assistantText));
   const metadata = [
     "*Pi finished*",
-    ...metadataLines(payload.metadata).map((line) => escapeMarkdownV2(line)),
+    ...markdownMetadataLines(payload.metadata),
     "",
     assistantText,
   ];
@@ -47,7 +74,7 @@ export function buildMarkdownMessage(payload: NotificationPayload): string {
 export function buildLongOutputPlainTextNotice(payload: NotificationPayload): string {
   return [
     "Pi finished",
-    ...metadataLines(payload.metadata),
+    ...plainMetadataLines(payload.metadata),
     "",
     "Full output attached as pi-notify-output.md",
   ].join("\n");
@@ -56,7 +83,7 @@ export function buildLongOutputPlainTextNotice(payload: NotificationPayload): st
 export function buildLongOutputMarkdownNotice(payload: NotificationPayload): string {
   return [
     "*Pi finished*",
-    ...metadataLines(payload.metadata).map((line) => escapeMarkdownV2(line)),
+    ...markdownMetadataLines(payload.metadata),
     "",
     escapeMarkdownV2("Full output attached as pi-notify-output.md"),
   ].join("\n");
@@ -69,6 +96,7 @@ export function buildAttachmentFilename(metadata: NotificationMetadata): string
 
 export function buildAttachmentMarkdown(payload: NotificationPayload): string {
   const modelLine = payload.metadata.model ? `- Model: ${payload.metadata.model}` : undefined;
+  const sessionLine = payload.metadata.sessionUrl ? `- Session: ${payload.metadata.sessionUrl}` : undefined;
 
   return [
     "# Pi finished",
@@ -77,6 +105,7 @@ export function buildAttachmentMarkdown(payload: NotificationPayload): string {
     `- CWD: ${payload.metadata.cwd}`,
     `- Time: ${payload.metadata.timestamp}`,
     ...(modelLine ? [modelLine] : []),
+    ...(sessionLine ? [sessionLine] : []),
     "",
     "## Assistant output",
     "",

package/src/index.ts

@@ -1,10 +1,84 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 
+import {
+  getNotifySessionUrlTemplate,
+  NOTIFY_CONFIG_PATH,
+  setNotifySessionUrlTemplate,
+} from "./config.js";
 import { PiNotifyController } from "./controller.js";
 
-export default function registerPiNotify(pi: ExtensionAPI): void {
+export interface RegisterPiNotifyOptions {
+  configPath?: string;
+}
+
+const CLEAR_URL_TEMPLATE_ARGS = new Set(["clear", "disable", "disabled", "none", "off"]);
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function notify(ctx: Pick<ExtensionCommandContext, "hasUI" | "ui">, message: string, type: "info" | "warning" | "error"): void {
+  if (ctx.hasUI) {
+    ctx.ui.notify(message, type);
+  }
+}
+
+export async function handlePiNotifyUrlCommand(
+  args: string,
+  ctx: ExtensionCommandContext,
+  configPath = NOTIFY_CONFIG_PATH,
+): Promise<void> {
+  const trimmedArgs = args.trim();
+
+  try {
+    if (!trimmedArgs) {
+      const currentTemplate = await getNotifySessionUrlTemplate(configPath);
+      if (currentTemplate) {
+        notify(ctx, `pi-notify: current session URL template is ${currentTemplate}`, "info");
+      } else {
+        notify(ctx, "pi-notify: session URL template is not set.", "info");
+      }
+      return;
+    }
+
+    if (CLEAR_URL_TEMPLATE_ARGS.has(trimmedArgs.toLowerCase())) {
+      await setNotifySessionUrlTemplate(undefined, configPath);
+      notify(ctx, `pi-notify: cleared session URL template in ${configPath}.`, "info");
+      return;
+    }
+
+    if (!trimmedArgs.includes("SESSION_ID")) {
+      notify(
+        ctx,
+        "pi-notify: URL template must include SESSION_ID. Example: /pi-notify-url https://archi.example/#SESSION_ID",
+        "warning",
+      );
+      return;
+    }
+
+    await setNotifySessionUrlTemplate(trimmedArgs, configPath);
+    notify(ctx, `pi-notify: saved session URL template to ${configPath}.`, "info");
+  } catch (error) {
+    notify(ctx, `pi-notify: failed to update session URL template: ${describeError(error)}`, "warning");
+  }
+}
+
+export default function registerPiNotify(pi: ExtensionAPI, options: RegisterPiNotifyOptions = {}): void {
+  const configPath = options.configPath ?? NOTIFY_CONFIG_PATH;
   const controller = new PiNotifyController();
 
+  pi.registerCommand("pi-notify-url", {
+    description: "Set or clear the session URL template used in Telegram notifications",
+    getArgumentCompletions: (prefix) => {
+      const suggestions = ["off", "clear"];
+      const filtered = suggestions.filter((value) => value.startsWith(prefix));
+      return filtered.length > 0 ? filtered.map((value) => ({ value, label: value })) : null;
+    },
+    handler: async (args, ctx) => {
+      await handlePiNotifyUrlCommand(args, ctx, configPath);
+    },
+  });
+
   pi.on("agent_end", async (event, ctx) => {
     await controller.handleAgentEnd(event.messages, ctx);
   });

package/src/types.ts

@@ -1,13 +1,16 @@
 export interface NotifyConfig {
   botToken: string;
   chatId: string;
+  sessionUrlTemplate?: string;
 }
 
 export interface NotificationMetadata {
   project: string;
   cwd: string;
   timestamp: string;
+  sessionId: string;
   model?: string;
+  sessionUrl?: string;
 }
 
 export interface NotificationPayload {