@llblab/pi-telegram 0.36.2 → 0.36.4

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.36.4: Async Host Settings Compatibility
+
+- `Async Host Settings`: Normalizes synchronous or asynchronous settings construction plus legacy enabled-model methods or generic `get` / `set` services at the Pi adapter boundary before model-menu reads and scoped-model persistence, improving compatible-host interoperability without changing native Pi behavior or weakening required `agent_settled` semantics.
+
+## 0.36.3: Ordered Prompt Compatibility
+
+- `Prompt Compatibility`: Preserves plain and ordered-block system prompts across Pi-compatible runtimes; Telegram guidance remains a distinct block when the host supplies blocks, while unavailable transport strips only Telegram tool metadata without collapsing unrelated prompt context.
+
 ## 0.36.2: Provider-Compatible Controls
 
 - `Provider-Compatible Bind Schema`: Exposes `telegram_bind` through one top-level JSON object schema while retaining runtime enforcement of mutually exclusive install and invocation forms, avoiding providers that reject top-level union schemas before any tool call can run.

package/README.md

@@ -28,6 +28,8 @@ pi install git:github.com/llblab/pi-telegram
 
 The 0.21 extension platform requires Pi `0.80.6` or newer. Its Activity API uses the public `agent_settled` lifecycle event to keep retries/continuations under one activity identity and release that identity only after the run fully settles.
 
+Pi is the primary and only officially supported host. Narrow host-neutral adapters preserve ordered prompt blocks and normalize synchronous or asynchronous legacy/generic settings services for Pi-compatible hosts, but this is best-effort compatibility rather than an OMP support guarantee. Alternate-host shims must still reproduce required Pi lifecycle semantics—especially `agent_settled`—and their maintainers own ongoing validation.
+
 ## Quick Start
 
 ### 1. Create a Telegram bot

package/docs/architecture.md

@@ -88,6 +88,16 @@ The repository uses a **Flat Domain DAG**:
 - `bindings` / `lifecycle` / `prompts` / `prompt-templates` / `pi`: Pi-facing command/tool/hook registration and cohesive cross-domain binding assembly, including queue mutation/dispatch/watchdog composition over admission and transport ports; session-generation fencing and start/shutdown sequencing across Queue, grouped input, Delivery, polling, capability monitor, follower refresh, and assistant-output projection; Telegram prompt guidance; prompt-template discovery/expansion; and centralized direct Pi SDK imports.
 - `command-templates`: shell-free command-template helpers, composition expansion, placeholder substitution, executable resolution, warnings, and retry/timeout semantics.
 
+### Host Compatibility Boundary
+
+Pi is the primary and only officially supported host. `pi-telegram` may still accept narrow, host-neutral representation differences at its existing Pi-facing boundary when they preserve native Pi behavior and do not create a second runtime policy layer:
+
+- `prompts` preserves either Pi's plain system-prompt string or an ordered block array supplied by a compatible host, appending Telegram guidance without collapsing host-owned blocks.
+- `pi` normalizes settings-manager construction that is either synchronous or asynchronous, then adapts either Pi's legacy enabled-model methods or a generic `get` / `set` settings service before model-menu reads and scoped-model persistence use it. Hosts without an explicit reload method rely on fresh asynchronous construction; durable writes still require `flush`.
+- `lifecycle` continues to require Pi's semantic `agent_settled` boundary. It does not infer terminal settlement from host-specific `agent_end`, retry, or stop events; a compatibility shim must reproduce that contract before it can safely support activity identity and unrecovered-error finalization.
+
+This boundary uses no host-name detection, host package dependency, prototype patching, hidden agent process, PTY, or terminal forwarding. Representation adapters are best-effort compatibility rather than an OMP support guarantee. Alternate hosts and community contributors own validation of their compatibility shims and must supply every lifecycle semantic that the bridge requires.
+
 ### Guarded Invariants
 
 Architecture invariant tests protect:

package/lib/lifecycle.ts

@@ -40,8 +40,15 @@ export function createAgentStartDedupHook(
   };
 }
 
+type TelegramBeforeAgentStartEvent = Omit<
+  BeforeAgentStartEvent,
+  "systemPrompt"
+> & {
+  systemPrompt: string | string[];
+};
+
 export interface TelegramBeforeAgentStartResult {
-  systemPrompt?: string;
+  systemPrompt?: string | string[];
 }
 
 type TelegramBeforeAgentStartReturn =
@@ -72,7 +79,7 @@ export interface TelegramLifecycleRegistrationDeps {
     ctx: ExtensionContext,
   ) => Promise<void> | void;
   onBeforeAgentStart: (
-    event: BeforeAgentStartEvent,
+    event: TelegramBeforeAgentStartEvent,
     ctx: ExtensionContext,
   ) => TelegramBeforeAgentStartReturn;
   onModelSelect: (
@@ -581,7 +588,16 @@ export function registerTelegramLifecycleHooks(
     if (!isActive(ctx)) return;
     await deps.onSessionCompact?.(event, ctx);
   });
-  pi.on("before_agent_start", async (event, ctx) => {
+  // The Pi SDK still types this result as a string; compatible runtimes may
+  // preserve ordered system prompt blocks through the same public hook.
+  const registerBeforeAgentStart = pi.on.bind(pi) as unknown as (
+    event: "before_agent_start",
+    handler: (
+      event: TelegramBeforeAgentStartEvent,
+      ctx: ExtensionContext,
+    ) => TelegramBeforeAgentStartReturn,
+  ) => void;
+  registerBeforeAgentStart("before_agent_start", async (event, ctx) => {
     return deps.onBeforeAgentStart(event, ctx);
   });
   pi.on("model_select", async (event, ctx) => {

package/lib/menu-model.ts

@@ -119,7 +119,9 @@ export interface TelegramModelMenuStateBuilderDeps<
     TelegramModelMenuStateBuilderContext<TModel>,
 > {
   runtime: TelegramModelMenuRuntime<TModel>;
-  createSettingsManager: (cwd: string) => MenuSettingsManager;
+  createSettingsManager: (
+    cwd: string,
+  ) => MenuSettingsManager | PromiseLike<MenuSettingsManager>;
   getActiveModel: (ctx: TContext) => TModel | undefined;
 }
 
@@ -490,7 +492,7 @@ export function createTelegramModelMenuStateBuilder<
   threadId?: number,
 ) => Promise<TelegramModelMenuState<TModel>> {
   return async (chatId, ctx, threadId) => {
-    const settingsManager = deps.createSettingsManager(ctx.cwd);
+    const settingsManager = await deps.createSettingsManager(ctx.cwd);
     return deps.runtime.buildState({
       chatId,
       threadId,

package/lib/pi.ts

@@ -151,16 +151,82 @@ export function createExtensionApiRuntimePorts(
   };
 }
 
-export function createSettingsManager(cwd: string): PiSettingsManager {
-  return SettingsManager.create(cwd);
+type PiSettingsManagerFactory = {
+  create: (cwd: string) => unknown | PromiseLike<unknown>;
+};
+
+type HostSettingsManager = {
+  reload?: () => void | PromiseLike<void>;
+  flush?: () => void | PromiseLike<void>;
+  getEnabledModels?: () => unknown;
+  setEnabledModels?: (patterns: string[] | undefined) => void;
+  get?: (key: string) => unknown;
+  set?: (key: string, value: unknown) => void;
+};
+
+function readEnabledModels(value: unknown): string[] | undefined {
+  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: unknown): PiSettingsManager {
+  if (typeof manager !== "object" || manager === null) {
+    throw new TypeError("Host settings manager must be an object.");
+  }
+  const host = manager as HostSettingsManager;
+  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: string[] | undefined) =>
+        host.setEnabledModels!.call(host, patterns)
+    : typeof host.set === "function"
+      ? (patterns: string[] | undefined) =>
+          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: string,
+): Promise<PiSettingsManager> {
+  // 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 as unknown as PiSettingsManagerFactory;
+  return normalizeSettingsManager(await factory.create(cwd));
 }
 
 export function createScopedModelPatternPersister(deps: {
-  createSettingsManager: (cwd: string) => PiSettingsManager;
+  createSettingsManager: (
+    cwd: string,
+  ) => PiSettingsManager | PromiseLike<PiSettingsManager>;
   clearCachedModelMenuInputs: () => void;
 }): (patterns: string[], ctx: ExtensionContext) => Promise<void> {
   return async (patterns, ctx) => {
-    const settingsManager = deps.createSettingsManager(ctx.cwd);
+    const settingsManager = await deps.createSettingsManager(ctx.cwd);
     settingsManager.setEnabledModels(
       patterns.length > 0 ? patterns : undefined,
     );

package/lib/prompts.ts

@@ -31,6 +31,15 @@ export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
   "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread.",
 ] as const;
 
+const TELEGRAM_TOOL_METADATA_LINES = Object.fromEntries(
+  [
+    `- telegram_attach: ${TELEGRAM_ATTACH_PROMPT_SNIPPET}`,
+    `- telegram_message: ${TELEGRAM_MESSAGE_PROMPT_SNIPPET}`,
+    ...TELEGRAM_ATTACH_PROMPT_GUIDELINES.map((line) => `- ${line}`),
+    ...TELEGRAM_MESSAGE_PROMPT_GUIDELINES.map((line) => `- ${line}`),
+  ].map((line) => [line, true]),
+) as Record<string, true>;
+
 const TELEGRAM_MODEL_CONTEXT_TOOL_NAMES = new Set([
   "telegram_attach",
   "telegram_bind",
@@ -132,13 +141,30 @@ export function createTelegramModelContextAvailabilityRuntime(deps: {
   };
 }
 
+export type TelegramSystemPrompt = string | string[];
+
+type TelegramBeforeAgentStartEvent = Omit<
+  BeforeAgentStartEvent,
+  "systemPrompt"
+> & {
+  systemPrompt: TelegramSystemPrompt;
+};
+
+type TelegramBeforeAgentStartResult = {
+  systemPrompt: TelegramSystemPrompt;
+};
+
+type TelegramBeforeAgentStartHook = (
+  event: TelegramBeforeAgentStartEvent,
+) => TelegramBeforeAgentStartResult;
+
 export function buildTelegramBridgeSystemPrompt(options: {
   prompt: string;
-  systemPrompt: string;
+  systemPrompt: TelegramSystemPrompt;
   telegramPrefix?: string;
   localSystemPromptSuffix: string;
   telegramTurnSystemPromptSuffix: string;
-}): { systemPrompt: string } {
+}): TelegramBeforeAgentStartResult {
   const telegramPrefix = options.telegramPrefix ?? TELEGRAM_PREFIX;
   const telegramHead = telegramPrefix.endsWith("]")
     ? telegramPrefix.slice(0, -1)
@@ -151,8 +177,14 @@ export function buildTelegramBridgeSystemPrompt(options: {
     ? `${options.telegramTurnSystemPromptSuffix}\n- The current user message came from Telegram.`
     : "";
   return {
-    systemPrompt:
-      options.systemPrompt + options.localSystemPromptSuffix + telegramSuffix,
+    systemPrompt: Array.isArray(options.systemPrompt)
+      ? [
+          ...options.systemPrompt,
+          options.localSystemPromptSuffix + telegramSuffix,
+        ]
+      : options.systemPrompt +
+        options.localSystemPromptSuffix +
+        telegramSuffix,
   };
 }
 
@@ -162,7 +194,7 @@ export function createTelegramBeforeAgentStartHook(
     localSystemPromptSuffix?: string;
     telegramTurnSystemPromptSuffix?: string;
   } = {},
-): (event: BeforeAgentStartEvent) => { systemPrompt: string } {
+): TelegramBeforeAgentStartHook {
   return (event) =>
     buildTelegramBridgeSystemPrompt({
       prompt: event.prompt,
@@ -176,23 +208,23 @@ export function createTelegramBeforeAgentStartHook(
     });
 }
 
-function stripTelegramToolMetadataFromSystemPrompt(
-  systemPrompt: string,
-): string {
-  const telegramLines = new Set([
-    `- telegram_attach: ${TELEGRAM_ATTACH_PROMPT_SNIPPET}`,
-    `- telegram_message: ${TELEGRAM_MESSAGE_PROMPT_SNIPPET}`,
-    ...TELEGRAM_ATTACH_PROMPT_GUIDELINES.map((line) => `- ${line}`),
-    ...TELEGRAM_MESSAGE_PROMPT_GUIDELINES.map((line) => `- ${line}`),
-  ]);
+function stripTelegramToolMetadataFromString(systemPrompt: string): string {
   return systemPrompt
     .split("\n")
-    .filter((line) => !telegramLines.has(line))
+    .filter((line) => TELEGRAM_TOOL_METADATA_LINES[line] !== true)
     .join("\n");
 }
 
+function stripTelegramToolMetadataFromSystemPrompt(
+  systemPrompt: TelegramSystemPrompt,
+): TelegramSystemPrompt {
+  return Array.isArray(systemPrompt)
+    ? systemPrompt.map(stripTelegramToolMetadataFromString)
+    : stripTelegramToolMetadataFromString(systemPrompt);
+}
+
 export interface TelegramProactivePromptHookDeps<TContext> {
-  baseHook?: (event: BeforeAgentStartEvent) => { systemPrompt: string };
+  baseHook?: TelegramBeforeAgentStartHook;
   reconcileAvailability?: () => void;
   isAvailable: (ctx: TContext) => boolean;
 }
@@ -200,9 +232,9 @@ export interface TelegramProactivePromptHookDeps<TContext> {
 export function createTelegramProactiveBeforeAgentStartHook<TContext>(
   deps: TelegramProactivePromptHookDeps<TContext>,
 ): (
-  event: BeforeAgentStartEvent,
+  event: TelegramBeforeAgentStartEvent,
   ctx: TContext,
-) => Promise<{ systemPrompt: string }> {
+) => Promise<TelegramBeforeAgentStartResult> {
   const baseHook = deps.baseHook ?? createTelegramBeforeAgentStartHook();
   return async (event, ctx) => {
     deps.reconcileAvailability?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.36.2",
+  "version": "0.36.4",
   "private": false,
   "publishConfig": {
     "access": "public"