pi-braid-telegram 0.0.0-stage → 0.1.4

package/src/lib/notify/model.ts

@@ -0,0 +1,197 @@
+/**
+ * turn-complete notify — key-ring-backed crafting model call.
+ *
+ * The notify model call reuses "our systems" — NOT the telegram bot token.
+ * It resolves a model + API key through the pi extension context's
+ * modelRegistry, which pi-braid-providers wires to the key-ring
+ * (ring-lifecycle.ts auth.apiKey.resolve → getActiveKey()). This mirrors the
+ * extension→LLM path used by core's llm-call.ts: completeSimple from
+ * @earendil-works/pi-ai/compat, with the key coming from the provider, never
+ * from telegram credentials.
+ *
+ * Model selection policy:
+ *   1. BRAID_TG_NOTIFY_MODEL override (env, "provider/model-id" or "model-id")
+ *   2. ctx.model (the session model)
+ *   3. first available model in the registry
+ */
+
+import type { Context, Message, Model, Api } from "@earendil-works/pi-ai";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import {
+  buildNotifyPrompts,
+  buildRichSummaryPrompts,
+  type NotifyFormat,
+} from "./craft.js";
+
+/** Minimal registry surface used here (subset of pi-core ModelRegistry). */
+export interface NotifyModelRegistry {
+  find?(provider: string, modelId: string): Model<Api> | undefined;
+  getAll?(): Model<Api>[];
+  getAvailable?(): Model<Api>[];
+  getApiKeyForProvider?(provider: string): Promise<string | undefined>;
+  hasConfiguredAuth?(model: Model<Api>): boolean;
+}
+
+/**
+ * Resolve the notify model. `configuredPattern` is an optional env override
+ * shaped like "provider/model-id" (or bare "model-id"); falls back to the
+ * session model, then the first available registry model.
+ */
+export function resolveNotifyModel(
+  registry: NotifyModelRegistry,
+  sessionModel: Model<Api> | undefined,
+  configuredPattern?: string,
+): Model<Api> | undefined {
+  if (configuredPattern?.trim()) {
+    const pattern = configuredPattern.trim();
+    const slash = pattern.indexOf("/");
+    if (slash >= 0) {
+      const provider = pattern.slice(0, slash);
+      const modelId = pattern.slice(slash + 1);
+      const found = registry.find?.(provider, modelId);
+      if (found) return found;
+    } else {
+      const all = registry.getAll?.() ?? [];
+      const found = all.find(
+        (m) => m.id === pattern || m.id.endsWith(`/${pattern}`),
+      );
+      if (found) return found;
+    }
+  }
+  if (sessionModel) return sessionModel;
+  const available = registry.getAvailable?.() ?? registry.getAll?.() ?? [];
+  return available[0];
+}
+
+/** Output budget of a bare craft call (legacy default — targets fit in it). */
+export const DEFAULT_CRAFT_MAX_TOKENS = 200;
+
+/**
+ * Output-token budget for a craft target of `chars` characters. A cap the
+ * model cannot reach ends in mid-sentence (a visibly compressed message),
+ * so the budget scales with the target: ~2 chars/token, floored at 512 and
+ * capped at 4096 tokens. The turn-notify path passes this for notifyMaxChars.
+ */
+export function craftMaxTokensFor(chars: number): number {
+  return Math.min(4096, Math.max(512, Math.ceil(chars / 2)));
+}
+
+/** Payload returned by the crafting call. */
+export interface CraftModelResult {
+  ok: boolean;
+  text?: string;
+  error?: string;
+}
+
+/**
+ * Make the crafting call. Returns the distilled text on success, or a
+ * non-throwing { ok:false } on failure so the caller can fall back to the
+ * truncation guard. Injectable completeSimple for deterministic tests.
+ */
+export async function callCraftModel(
+  registry: NotifyModelRegistry,
+  model: Model<Api>,
+  prompts: { system: string; user: string },
+  opts: {
+    completeSimpleFn?: typeof completeSimple;
+    signal?: AbortSignal;
+    /** Output token budget (default DEFAULT_CRAFT_MAX_TOKENS = 200). */
+    maxTokens?: number;
+  } = {},
+): Promise<CraftModelResult> {
+  try {
+    let apiKey: string | undefined;
+    if (registry.getApiKeyForProvider) {
+      apiKey = await registry.getApiKeyForProvider(model.provider);
+    }
+    const fn = opts.completeSimpleFn ?? completeSimple;
+    const context: Context = {
+      systemPrompt: prompts.system,
+      messages: [
+        {
+          role: "user",
+          content: prompts.user,
+          timestamp: Date.now(),
+        } satisfies Message,
+      ],
+    };
+    const assistant = await fn(model as Model<Api>, context, {
+      apiKey,
+      maxTokens: opts.maxTokens ?? DEFAULT_CRAFT_MAX_TOKENS,
+      temperature: 0.2,
+      signal: opts.signal,
+    });
+    if (assistant.errorMessage) {
+      return { ok: false, error: assistant.errorMessage };
+    }
+    const text = (assistant.content ?? [])
+      .filter((c): c is { type: "text"; text: string } => c.type === "text")
+      .map((c) => c.text)
+      .join("\n")
+      .trim();
+    if (!text)
+      return { ok: false, error: "empty response from crafting model" };
+    return { ok: true, text };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Build the text-crafting hook used by telegram_send and /telegram send: given
+ * a too-long message, distill it to a concise owner update (≤ the applicable
+ * send cap). Returns `null` when no model is resolvable or the call fails —
+ * the caller ERRORS rather than truncating silently. Key-ring-backed
+ * (modelRegistry), never the bot token. `opt.prompts` swaps the prompt builder
+ * (rich summaries vs concise distills).
+ */
+export function createTextCraftHook(
+  registry: NotifyModelRegistry,
+  sessionModel: Model<Api> | undefined,
+  configuredPattern?: string,
+  opts: {
+    completeSimpleFn?: typeof completeSimple;
+    signal?: AbortSignal;
+    prompts?: (text: string) => { system: string; user: string };
+  } = {},
+): (text: string) => Promise<{ text: string; crafted: boolean } | null> {
+  const promptsBuilder = opts.prompts ?? buildNotifyPrompts;
+  return async (
+    text: string,
+  ): Promise<{ text: string; crafted: boolean } | null> => {
+    const model = resolveNotifyModel(registry, sessionModel, configuredPattern);
+    if (!model) return null;
+    const prompts = promptsBuilder(text);
+    const result = await callCraftModel(registry, model, prompts, opts);
+    if (!result.ok || !result.text) return null;
+    return { text: result.text, crafted: true };
+  };
+}
+
+/**
+ * Rich-summary crafting hook for the live-update final report: same
+ * key-ring-backed path as `createTextCraftHook`, but the prompt builder is the
+ * rich variant (buildRichSummaryPrompts) — the report may be long and
+ * formatted; split-to-fit handles the Telegram 4096 cap downstream. `opts.mode`
+ * selects which markup the prompt asks for (default Markdown); the delivery
+ * layer still re-guards the crafted body.
+ */
+export function createRichCraftHook(
+  registry: NotifyModelRegistry,
+  sessionModel: Model<Api> | undefined,
+  configuredPattern?: string,
+  opts: {
+    completeSimpleFn?: typeof completeSimple;
+    signal?: AbortSignal;
+    mode?: NotifyFormat;
+  } = {},
+): (text: string) => Promise<{ text: string; crafted: boolean } | null> {
+  return createTextCraftHook(registry, sessionModel, configuredPattern, {
+    ...opts,
+    prompts: (text: string) =>
+      buildRichSummaryPrompts(text, opts.mode ?? "Markdown"),
+  });
+}

package/src/lib/notify/rate-limit.ts

@@ -0,0 +1,44 @@
+/**
+ * Sliding-window rate limiter for turn-complete auto-notify.
+ *
+ * Pure + deterministic: `try(now)` takes an explicit timestamp so tests can
+ * drive window boundaries without sleeping. The default policy (max N per
+ * minute) is a deployment default; the limiter itself is policy-agnostic.
+ */
+
+export interface SlidingWindowLimiterOptions {
+  /** Max notifications allowed per window. */
+  maxPerWindow: number;
+  /** Window length in ms. */
+  windowMs: number;
+}
+
+export class SlidingWindowLimiter {
+  private readonly maxPerWindow: number;
+  private readonly windowMs: number;
+  private hits: number[] = [];
+
+  constructor(opts: SlidingWindowLimiterOptions) {
+    if (!(opts.maxPerWindow > 0)) throw new Error("maxPerWindow must be > 0");
+    if (!(opts.windowMs > 0)) throw new Error("windowMs must be > 0");
+    this.maxPerWindow = opts.maxPerWindow;
+    this.windowMs = opts.windowMs;
+  }
+
+  /**
+   * Attempt to take a slot at `now`. Returns true when the call is allowed
+   * (and records it); false when the window is saturated.
+   */
+  try(now: number = Date.now()): boolean {
+    const cutoff = now - this.windowMs;
+    this.hits = this.hits.filter((t) => t > cutoff);
+    if (this.hits.length >= this.maxPerWindow) return false;
+    this.hits.push(now);
+    return true;
+  }
+
+  /** Clear all recorded hits (test helper / session reset). */
+  reset(): void {
+    this.hits = [];
+  }
+}

package/src/lib/notify/turn-notify.ts

@@ -0,0 +1,138 @@
+/**
+ * turn-complete auto-notify — turn_end handler orchestration.
+ *
+ * On turn_end with a completed plain-text answer (no trailing tool call):
+ *   1. rate-limit gate (max N per minute, sliding window)
+ *   2. distilling LLM call (via the injected model loader — key-ring-backed)
+ *   3. guard-fallback to the notifyMaxChars cap (crafting model produces the
+ *      message; the truncation rule stays only as a safety net)
+ *   4. deliver through the outbound seam (telegram client — no [tg-end])
+ *
+ * The handler is pure-of-network: the model call and delivery are injected so
+ * the fixture tests run deterministically with zero real LLM calls and zero
+ * network. Production wiring (src/index.ts) supplies the real implementations.
+ */
+
+import {
+  shouldNotifyTurnEnd,
+  extractFinalText,
+  buildNotifyPrompts,
+  truncateGuard,
+} from "./craft.js";
+import { SlidingWindowLimiter } from "./rate-limit.js";
+import {
+  craftMaxTokensFor,
+  type CraftModelResult,
+  type NotifyModelRegistry,
+} from "./model.js";
+import { resolveNotifyMaxChars } from "../telegram-settings.js";
+import type { Model, Api } from "@earendil-works/pi-ai";
+
+/** Model-call context bound from the turn_end ExtensionContext. */
+export interface NotifyModelCtx {
+  registry: NotifyModelRegistry;
+  sessionModel?: Model<Api> | undefined;
+}
+
+export interface TurnNotifyDeps {
+  /** Distilling model call. The model + key are resolved from `modelCtx`
+   *  inside the handler (key-ring-backed via ctx.modelRegistry). `opts.maxTokens`
+   *  is the output budget sized for the resolved notify cap — forward it to the
+   *  provider so a long target is not cut mid-sentence.
+   */
+  callModel(
+    prompts: { system: string; user: string },
+    modelCtx: NotifyModelCtx,
+    opts?: { maxTokens?: number },
+  ): Promise<CraftModelResult>;
+  /** Outbound delivery of the crafted text (≤ notifyMaxChars). Never [tg-end]-decorated. */
+  deliver(text: string): Promise<void> | void;
+  /** Clock (injectable for deterministic rate-limit tests). */
+  now?(): number;
+  /** Max auto-notifies per window. */
+  maxPerWindow?: number;
+  /** Sliding window length in ms. */
+  windowMs?: number;
+  /** Guard-fallback length cap override (default: braid.telegram.notifyMaxChars). */
+  maxLength?: number;
+}
+
+/** Shared defaults — policy surface for the design decision list. */
+export const DEFAULT_NOTIFY_MAX_PER_MIN = 4;
+export const DEFAULT_NOTIFY_WINDOW_MS = 60_000;
+
+export interface TurnNotifyOutcome {
+  notified: boolean;
+  /** Why nothing was sent (rate-limited / no text / model+guard both empty). */
+  skipped?: "rate-limited" | "no-answer-text" | "empty-result";
+  text?: string;
+}
+
+/**
+ * Build the turn_end handler. Non-throwing: any failure inside is swallowed and
+ * logged to the caller's sink — an auto-notify must never break the turn loop.
+ */
+export function createTurnNotifyHandler(
+  deps: TurnNotifyDeps,
+): (
+  event: unknown,
+  modelCtx: NotifyModelCtx,
+  log?: (m: string, t?: "info" | "warning" | "error") => void,
+) => Promise<TurnNotifyOutcome> {
+  const limiter = new SlidingWindowLimiter({
+    maxPerWindow: deps.maxPerWindow ?? DEFAULT_NOTIFY_MAX_PER_MIN,
+    windowMs: deps.windowMs ?? DEFAULT_NOTIFY_WINDOW_MS,
+  });
+  const now = deps.now ?? (() => Date.now());
+
+  /** Resolve the cap per call: explicit override, else settings (no caching). */
+  const resolveCap = (): number =>
+    typeof deps.maxLength === "number" &&
+    Number.isFinite(deps.maxLength) &&
+    deps.maxLength >= 1
+      ? Math.floor(deps.maxLength)
+      : resolveNotifyMaxChars();
+
+  return async (
+    event,
+    modelCtx,
+    log = () => {},
+  ): Promise<TurnNotifyOutcome> => {
+    try {
+      if (!shouldNotifyTurnEnd(event)) return { notified: false };
+      if (!limiter.try(now()))
+        return { notified: false, skipped: "rate-limited" };
+
+      const finalText = extractFinalText(event);
+      if (!finalText) return { notified: false, skipped: "no-answer-text" };
+
+      const cap = resolveCap();
+      const prompts = buildNotifyPrompts(finalText, cap);
+      const crafted = await deps.callModel(prompts, modelCtx, {
+        maxTokens: craftMaxTokensFor(cap),
+      });
+
+      // Crafting model produces the message; guard-truncate is the fallback.
+      const text = truncateGuard(
+        crafted.ok && crafted.text ? crafted.text : finalText,
+        cap,
+      );
+      if (!text) return { notified: false, skipped: "empty-result" };
+
+      await deps.deliver(text);
+      if (!crafted.ok) {
+        log(
+          `[telegram notify] crafting model failed (${crafted.error ?? "unknown"}) — delivered guard-truncated text`,
+          "warning",
+        );
+      }
+      return { notified: true, text };
+    } catch (err) {
+      log(
+        `[telegram notify] error: ${err instanceof Error ? err.message : String(err)}`,
+        "error",
+      );
+      return { notified: false };
+    }
+  };
+}