@llblab/pi-telegram 0.36.3 → 0.36.5

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.36.5: Separated Tool Errors
+
+- `Separated Tool Errors`: Prefixes Telegram attachment and direct-message Tool failures with one normalized leading newline so Pi renders error evidence on a visually separated line beneath the Tool name without changing the underlying diagnostic text.
+
+## 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.

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/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/outbound-attachments.ts

@@ -436,6 +436,11 @@ async function buildTelegramOutboundAttachmentViews(options: {
   return pendingAttachments;
 }
 
+function formatTelegramOutboundToolError(error: unknown): Error {
+  const message = error instanceof Error ? error.message : String(error);
+  return new Error(`\n${message.replace(/^\n+/u, "") || "Telegram outbound operation failed."}`);
+}
+
 export function registerTelegramOutboundAttachmentTool(
   pi: ExtensionAPI,
   deps: TelegramOutboundAttachmentToolRegistrationDeps,
@@ -496,7 +501,7 @@ export function registerTelegramOutboundAttachmentTool(
           phase: "queue",
           count: params.paths.length,
         });
-        throw error;
+        throw formatTelegramOutboundToolError(error);
       }
     },
   });
@@ -548,7 +553,7 @@ export function registerTelegramOutboundMessageTool(
         });
       } catch (error) {
         deps.recordRuntimeEvent?.("message", error, { phase: "direct" });
-        throw error;
+        throw formatTelegramOutboundToolError(error);
       }
     },
   });

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/package.json

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