@llblab/pi-telegram 0.43.2 → 0.45.0

package/lib/workspace-slots.ts

@@ -0,0 +1,84 @@
+/**
+ * Workspace slot allocation policy
+ * Zones: telegram, workspace identity
+ * Owns bounded profile-wide letter selection and inactivity ordering.
+ * Excludes liveness discovery, persistence, routing, and Telegram deletion;
+ * a selection is a proposal, never authority to retire a binding.
+ */
+
+export const TELEGRAM_WORKSPACE_SLOTS = "abcdefghijklmnopqrstuvwxyz";
+
+export interface TelegramWorkspaceSlotOccupancy {
+  bindingKey: string;
+  slot: string;
+  inactiveSinceMs?: number;
+  protection: "eligible" | "protected" | "unknown";
+}
+
+export type TelegramWorkspaceSlotAllocation =
+  | { kind: "free"; slot: string }
+  | { kind: "reclaim"; candidate: TelegramWorkspaceSlotOccupancy }
+  | { kind: "blocked"; reason: "invalid-state" | "protected-capacity" };
+
+function isSlot(slot: string): boolean {
+  return /^[a-z]$/u.test(slot);
+}
+
+function isValidSnapshot(
+  bindings: readonly TelegramWorkspaceSlotOccupancy[],
+  reservedSlots: readonly string[],
+  nowMs: number,
+): boolean {
+  if (!Number.isFinite(nowMs) || nowMs < 0) return false;
+  const slots = new Set<string>();
+  const keys = new Set<string>();
+  for (const binding of bindings) {
+    if (!isSlot(binding.slot) || !binding.bindingKey ||
+        slots.has(binding.slot) || keys.has(binding.bindingKey)) return false;
+    slots.add(binding.slot);
+    keys.add(binding.bindingKey);
+  }
+  return reservedSlots.every(isSlot);
+}
+
+function eligibleByInactivity(
+  bindings: readonly TelegramWorkspaceSlotOccupancy[],
+  reservedSlots: readonly string[],
+  nowMs: number,
+): TelegramWorkspaceSlotOccupancy[] {
+  const reserved = new Set(reservedSlots);
+  return bindings.filter((binding) =>
+    binding.protection === "eligible" &&
+    !reserved.has(binding.slot) &&
+    typeof binding.inactiveSinceMs === "number" &&
+    Number.isFinite(binding.inactiveSinceMs) &&
+    binding.inactiveSinceMs >= 0 &&
+    binding.inactiveSinceMs <= nowMs,
+  ).sort((left, right) =>
+    left.inactiveSinceMs! - right.inactiveSinceMs! ||
+    left.slot.charCodeAt(0) - right.slot.charCodeAt(0),
+  );
+}
+
+/** Caller must recheck exact ownership and protected work before retirement. */
+export function planTelegramWorkspaceSlotAllocation(input: {
+  bindings: readonly TelegramWorkspaceSlotOccupancy[];
+  reservedSlots: readonly string[];
+  nowMs: number;
+}): TelegramWorkspaceSlotAllocation {
+  const { bindings, reservedSlots, nowMs } = input;
+  if (!isValidSnapshot(bindings, reservedSlots, nowMs)) {
+    return { kind: "blocked", reason: "invalid-state" };
+  }
+  const occupied = new Set([
+    ...bindings.map((binding) => binding.slot),
+    ...reservedSlots,
+  ]);
+  for (const slot of TELEGRAM_WORKSPACE_SLOTS) {
+    if (!occupied.has(slot)) return { kind: "free", slot };
+  }
+  const candidate = eligibleByInactivity(bindings, reservedSlots, nowMs)[0];
+  return candidate
+    ? { kind: "reclaim", candidate: { ...candidate } }
+    : { kind: "blocked", reason: "protected-capacity" };
+}

package/package.json

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

package/scripts/measure-bus.mjs

@@ -0,0 +1,83 @@
+// Counts isolated registry work without sockets, configured profiles, or Telegram calls.
+import assert from "node:assert/strict";
+import { createTelegramBusFollowerRegistry, createTelegramBusProtocolIdentity } from "../lib/bus.ts";
+
+const repetitions = 10;
+const methods = ["get", "set", "delete", "entries", "values"];
+const originals = Object.fromEntries(methods.map((name) => [name, Map.prototype[name]]));
+const rows = [];
+let counts;
+
+function measure(size, operation, execute) {
+  const sample = { gets: 0, sets: 0, deletes: 0, entryVisits: 0, valueVisits: 0 };
+  let result;
+  counts = sample;
+  try {
+    for (let index = 0; index < repetitions; index++) result = execute(index);
+  } finally {
+    counts = undefined;
+  }
+  rows.push({ size, operation, repetitions, ...sample });
+  return { result, counts: sample };
+}
+
+try {
+  for (const [method, counter] of [["get", "gets"], ["set", "sets"], ["delete", "deletes"]]) {
+    Map.prototype[method] = function (...args) {
+      if (counts) counts[counter]++;
+      return originals[method].apply(this, args);
+    };
+  }
+  for (const [method, counter] of [["entries", "entryVisits"], ["values", "valueVisits"]]) {
+    Map.prototype[method] = function* (...args) {
+      for (const entry of originals[method].apply(this, args)) {
+        if (counts) counts[counter]++;
+        yield entry;
+      }
+    };
+  }
+  for (const size of [1, 13, 26]) {
+    const registry = createTelegramBusFollowerRegistry();
+    const protocol = createTelegramBusProtocolIdentity({ runtimeBuild: "measurement" });
+    const registrations = Array.from({ length: size }, (_, index) => ({
+      instanceId: `fixture-${index}`, profileKey: `manual:fixture-${index}`,
+      registrationGeneration: `generation-${index}`, connectedAtMs: 1000,
+      target: { chatId: 7, threadId: index + 1 }, protocol,
+    }));
+    for (const registration of registrations) registry.register(registration);
+    const last = registrations.at(-1);
+    const registered = measure(size, "reregister-last", () => registry.register(last));
+    assert.equal(registered.counts.entryVisits, size * repetitions);
+    const heartbeat = measure(size, "heartbeat-last", (index) => registry.heartbeat(last.instanceId, 2000 + index));
+    assert.equal(heartbeat.result.lastHeartbeatMs, 2000 + repetitions - 1);
+    assert.equal(heartbeat.counts.entryVisits + heartbeat.counts.valueVisits, 0);
+    assert.equal(heartbeat.counts.gets, repetitions);
+    assert.equal(heartbeat.counts.sets, repetitions);
+    const first = measure(size, "target-first", () => registry.getByTarget(registrations[0].target));
+    assert.equal(first.result.instanceId, registrations[0].instanceId);
+    assert.equal(first.counts.valueVisits, repetitions);
+    const tail = measure(size, "target-last", () => registry.getByTarget(last.target));
+    assert.equal(tail.result.instanceId, last.instanceId);
+    assert.equal(tail.counts.valueVisits, size * repetitions);
+    const missing = measure(size, "target-missing-chat", () => registry.getByTarget({ chatId: 8, threadId: size }));
+    assert.equal(missing.result, undefined);
+    assert.equal(missing.counts.valueVisits, size * repetitions);
+    const roster = measure(size, "list", () => registry.list());
+    assert.equal(roster.result.length, size);
+    assert.equal(roster.counts.valueVisits, size * repetitions);
+    for (const view of [registered.result, heartbeat.result, first.result, tail.result, ...roster.result]) {
+      const expected = registry.get(view.instanceId);
+      view.target.chatId = 99;
+      view.protocol.capabilities.push("fixture-only");
+      assert.deepEqual(registry.get(view.instanceId), expected, "Returned views must not mutate registry authority");
+    }
+  }
+} finally {
+  for (const method of methods) Map.prototype[method] = originals[method];
+}
+console.log(JSON.stringify({
+  scope: "Synchronous isolated follower registry, not IPC, authentication, provisioning, or throughput",
+  counters: "Aggregate Map operations and visited entries for each row's repetitions; no allocation or timing claims",
+  copyEvidence: "Mutating returned target/protocol capability views leaves registry authority unchanged",
+  rows,
+}, null, 2));

package/scripts/measure-workspace.mjs

@@ -0,0 +1,101 @@
+// Measures isolated Thread-store work; never reads configured profiles or calls Telegram.
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import { syncBuiltinESMExports } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTelegramTopicTargetStore } from "../lib/threads.ts";
+
+const repetitions = 10;
+const original = { readFile: fs.readFile, writeFile: fs.writeFile, mkdir: fs.mkdir, rename: fs.rename,
+  parse: JSON.parse, stringify: JSON.stringify };
+let counts;
+const rows = [];
+const root = await fs.mkdtemp(join(tmpdir(), "pi-telegram-measure-workspace-"));
+
+async function measure(size, operation, execute, samples = repetitions) {
+  counts = { reads: 0, readBytes: 0, writes: 0, writeBytes: 0, mkdirs: 0, renames: 0,
+    parses: 0, stringifies: 0 };
+  try {
+    for (let index = 0; index < samples; index++) await execute(index);
+    const result = { size, operation, repetitions: samples, ...counts };
+    rows.push(result);
+    return result;
+  } finally {
+    counts = undefined;
+  }
+}
+
+try {
+  fs.readFile = async (...args) => {
+    if (counts) counts.reads++;
+    const result = await original.readFile(...args);
+    if (counts) counts.readBytes += Buffer.byteLength(result);
+    return result;
+  };
+  fs.writeFile = async (...args) => {
+    if (counts) { counts.writes++; counts.writeBytes += Buffer.byteLength(args[1]); }
+    return original.writeFile(...args);
+  };
+  fs.mkdir = async (...args) => {
+    if (counts) counts.mkdirs++;
+    return original.mkdir(...args);
+  };
+  fs.rename = async (...args) => {
+    if (counts) counts.renames++;
+    return original.rename(...args);
+  };
+  JSON.parse = (...args) => { if (counts) counts.parses++; return original.parse(...args); };
+  JSON.stringify = (...args) => { if (counts) counts.stringifies++; return original.stringify(...args); };
+  syncBuiltinESMExports();
+
+  for (const size of [1, 13, 26]) {
+    const path = join(root, `${size}.json`);
+    const store = createTelegramTopicTargetStore({ path, getNowMs: () => 1000 });
+    for (let index = 0; index < size; index++) {
+      const instanceId = `fixture-${index}`;
+      const identity = store.claimWorkspaceIdentity(`/fixture/${index}`, instanceId);
+      assert.ok(identity);
+      const target = { chatId: 7, threadId: index + 1 };
+      assert.ok(store.upsertWorkspaceBinding({ ...identity, target, updatedAtMs: 1000 }, instanceId));
+      store.upsert({ profileKey: `manual:${instanceId}`, instanceId, slot: identity.slot,
+        target, status: "active", createdAtMs: 1000, updatedAtMs: 1000 });
+    }
+    await store.persist();
+    assert.equal(new Set(store.listWorkspaceBindings().map((entry) => entry.slot)).size, size);
+    await measure(size, "cold-load", async () => {
+      const reader = createTelegramTopicTargetStore({ path });
+      await reader.load();
+      assert.equal(reader.list().length, size);
+      assert.equal(reader.listWorkspaceBindings().length, size);
+    });
+    const lookup = await measure(size, "lookup-last", () => {
+      assert.equal(store.getByProfileKey(`manual:fixture-${size - 1}`)?.target.threadId, size);
+    });
+    assert.equal(lookup.reads + lookup.writes, 0);
+    const beforeReloadSave = JSON.parse(await fs.readFile(path, "utf8"));
+    const reloaded = await measure(size, "first-persist-after-reload", () => store.persist(), 1);
+    assert.equal(reloaded.writes + reloaded.renames + reloaded.mkdirs, 0);
+    assert.deepEqual(JSON.parse(await fs.readFile(path, "utf8")), beforeReloadSave,
+      "The first reloaded save must preserve the seeded semantic state");
+    const unchanged = await measure(size, "unchanged-persist", () => store.persist());
+    assert.equal(unchanged.writes + unchanged.renames + unchanged.mkdirs, 0);
+    assert.ok(unchanged.reads >= repetitions, "No-op saves still consult disk authority");
+    const changed = await measure(size, "diagnostic-persist", async (index) => {
+      store.setStatusSnapshot({ diagnostics: { measurementStep: index } });
+      await store.persist();
+    });
+    assert.equal(changed.writes, repetitions);
+    assert.equal(changed.renames, repetitions);
+  }
+} finally {
+  Object.assign(fs, { readFile: original.readFile, writeFile: original.writeFile,
+    mkdir: original.mkdir, rename: original.rename });
+  JSON.parse = original.parse;
+  JSON.stringify = original.stringify;
+  syncBuiltinESMExports();
+  await fs.rm(root, { recursive: true, force: true });
+}
+console.log(JSON.stringify({ scope: "Isolated Thread store, not IPC/admission/Telegram or throughput",
+  counters: "Aggregate API calls and bytes for each row's repetitions; object-spread clones are not instrumented",
+  rows }, null, 2));

package/skills/show-me/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: show-me
+description: Explain completed work, proposed changes, system structure, or ideas through truthful contextual Markdown, concise diagrams, code-shape sketches, and focused HTML artifacts. Use when the user asks to show what happened, what changed, or how something works, especially on a phone-width Telegram surface.
+---
+
+Help the user understand the current topic. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear without making the underlying claim less true.
+
+### Output Selection
+
+- Infer the subject from the conversation and honor an explicitly requested format. With plain `show me`, choose the form that best explains the subject.
+- Markdown in the reply is a complete output format for both chat and terminal surfaces. Use headings, emphasis, lists, and focused code blocks to explain outcomes, comparisons, and reasoning; add a diagram when relationships need one.
+- `Show me markdown` requests a rendered Markdown reply. Create a Markdown file only when the user asks for a saved document or file artifact.
+- `Show me html` requests a focused HTML file. Save file artifacts in the project or filesystem as appropriate and deliver them through the active environment's file-delivery mechanism; open locally when that is the requested surface.
+
+### Surface Routing
+
+- Infer whether the active surface is Telegram, a terminal, or another client. Keep the explanation portable and use surface-specific delivery only when the context or user request authorizes it.
+- For Telegram output, read [`references/telegram-surfaces.md`](./references/telegram-surfaces.md) before selecting Markdown or HTML. Keep the immediate reply useful even when an attached artifact is the deeper view.
+- When asked what changed or happened in current work, inspect the retained diff, status, and validation evidence when available. Separate this task from pre-existing changes and distinguish repository state from released or live behavior.
+
+### Truth And State
+
+- Label material claims as `live`, `released`, `locally implemented`, `proposed`, or `unverified` when the distinction affects interpretation. Omit redundant labels when the state is already unambiguous.
+- Preserve the exact mechanism, owner, and boundary when simplifying technical behavior. A friendly label may supplement the implementation term but must not replace it when that would merge distinct timers, states, stages, or authorities.
+- Make a visual diff correspond to the actual changed symbol or contract. Show unchanged neighboring behavior when omission could imply that it changed too.
+- Do not infer that an affordance is clickable, interactive, rendered, or client-visible from source or markup shape alone. Distinguish designed or expected behavior from behavior verified through the relevant renderer, transport, runtime, and client.
+- Treat a mockup, diagram, or rendered artifact as explanatory evidence, not runtime proof. State the unverified boundary when the user could reasonably mistake one for the other.
+
+A compact state line is enough when provenance matters:
+
+```text
+State: locally implemented · validated · not released · not live
+```
+
+### Visual Forms
+
+- Show logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+- Show runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+- Show UI structure as a component tree, including state and module boundaries that matter:
+
+```tsx
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+- Show file responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├─ commands/
+│  └─ parses user actions
+├─ sessions/
+│  └─ owns session state
+└─ transport/
+   └─ sends API requests
+```
+
+- Show component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+- Use `diff` when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
+
+For a component change:
+
+```diff
+ <SessionPage>
+   useSessionEvents()
+   <SessionToolbar>
++    <RunSkillButton />
+   <SessionTimeline>
++    <SkillResultCard />
+```
+
+For a file-layout change:
+
+```diff
+ src/
+ ├─ commands/
++│  └─ show-me.ts
++│     └─ expands the slash command
+ ├─ sessions/
+-└─ transport.ts
++└─ transport/
++   ├─ client.ts
++   └─ stream.ts
+```
+
+For a call-tree or call-stack change:
+
+```diff
+ submitForm
+   createSession
+     persistPrompt
++    expandSkillMention
+     launchAgent
+-  navigateToSession
++  navigateToSession
++    subscribeToEvents
+```
+
+For a state or control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+- Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1)
+  return `use the ${skillName} skill`
+}
+```
+
+- For a visual UI, layout, state comparison, or concept too dense for Mermaid, use a focused HTML artifact — a diagram, an infographic, or a short slide deck, whichever fits the point. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile. When practical, render representative narrow and wide viewports and report what was actually inspected.
+
+### Text Rendering
+
+- Adapt the view to the available width in both terminal and chat surfaces. Use shallow trees with `├─`, `└─`, and `│`, a space before labels, and a three-column nesting step for file hierarchy; use indentation for call trees and pseudocode.
+- Keep labels concise and in the user's language. Express status with words; use text glyphs with predictable monospace width for aligned diagram structure.
+- For changes, use a compact fenced `diff` block in Telegram or the terminal. Show the changed lines and only the surrounding context needed to understand them.
+- In trees, place comments and explanations as child nodes one level below the item they describe. Keep the item's own line for its label.
+- Use prose lists for independent statuses and split larger views into meaningful sections.
+
+### Guidance
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point. Prefer one primary visual and a few decision-relevant takeaways; add another form only when it explains a different necessary relationship.
+
+Use source paths, symbol names, or validation evidence when they materially anchor a claim, not as decoration. Report the strongest state the evidence supports and no stronger.
+
+You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.

package/skills/show-me/references/telegram-surfaces.md

@@ -0,0 +1,43 @@
+# Telegram Explanation Surfaces
+
+Use this reference only when Show Me is responding through Telegram or preparing an artifact for Telegram delivery.
+
+## Selection
+
+- With plain `show me`, prefer a native Markdown reply when one phone-width view can explain the point.
+- Use HTML when spatial comparison, dense state, a timeline, or a visual hierarchy would become harder to understand in narrow Markdown.
+- `Show me markdown` means rendered Markdown in the current reply, not a `.md` attachment, unless the user explicitly asks for a file.
+- `Show me html` means one focused, self-contained `.html` artifact delivered through the active Telegram file path. The surrounding reply should say what the artifact explains and disclose its evidence state.
+- Do not create both formats by habit. The second format must answer a need the first cannot.
+
+## Telegram Markdown
+
+- Design for a phone before a desktop: one governing question, one primary visual, short labels, shallow nesting, and prose that wraps naturally.
+- Prefer compact semantic diffs, call trees, timelines, or state transitions over raw repository diffs. A remote user needs to understand impact before file-level detail.
+- Avoid wide tables, deep trees, side-by-side layouts, and Mermaid when the current Telegram renderer would expose only source text. Move genuinely spatial material to HTML.
+- Put material state near the top: what changed, whether it is local or live, what was validated, and what remains unresolved.
+- Keep source paths and symbol names below the explanation unless they are the explanation.
+- Keep intended Telegram bot-command tokens as plain text rather than inline code. Format Pi/TUI or shell commands as code according to the host contract. Plain source shape does not prove native clickability; claim it only after the active entity-detection and client path is verified.
+- Use explicit Markdown links when a destination matters rather than assuming plain URL auto-detection.
+
+## Telegram HTML
+
+- Produce a single self-contained file with UTF-8 metadata and a viewport declaration. Avoid external assets, scripts, fonts, trackers, or network requirements unless the user explicitly requested them.
+- Build mobile-first for roughly phone-width reading, then let the same document expand cleanly in a system or desktop browser. Text must wrap; diagrams must scroll or reflow without clipping.
+- Use semantic headings, sufficient contrast, non-color status meaning, comfortable touch targets, and no hover-only information.
+- Preserve real labels, values, ordering, and uncertainty. An attractive reconstruction must not invent runtime state or imply that a proposed interaction exists.
+- Include a compact provenance line when state matters, such as `Local patch · validated · not released · not live`.
+- When rendering tools are available, inspect at least one narrow viewport and one wider viewport. Report what was inspected; static source review is not visual proof.
+- Deliver the file through the active Telegram attachment mechanism. Do not expose local paths as if the user could open them remotely.
+
+## Current-Work Evidence
+
+Before explaining “what we did” or “what happened,” use the narrowest available evidence that can support the answer:
+
+1. Inspect retained repository status and diff for the relevant task.
+2. Identify pre-existing or unrelated changes and exclude them from the claimed task result.
+3. Name the actual changed mechanism or contract, not a friendlier neighboring concept.
+4. Separate implementation evidence from validation, release, deployment, runtime, transport, and client evidence.
+5. State unresolved causes or missing live checks instead of filling them with a cleaner story.
+
+A visual is successful when the user can understand the outcome away from a computer without being given a stronger claim than the evidence supports.

package/skills/telegram-bridge/references/delivery-and-threads.md

@@ -7,7 +7,7 @@ Read this reference only for explicit local/TUI Telegram delivery, cross-target
 Use `telegram_message` only when the user explicitly requests Telegram delivery from local/TUI or names a concrete different Telegram target.
 
 - Omitted target selects the paired/default target only outside an active Telegram turn.
-- `chat_id` plus optional `thread_id` selects an explicit Bot API target.
+- `chat_id` plus optional `thread_id` selects an explicit Bot API target. A public `@username`, or an exact negative numeric channel ID with `channel: true`, uses `chat_id` without `thread_id`; channel delivery requires the direct leader, and Telegram enforces the bot's posting permission.
 - `thread` selects another live Pi Thread by case-insensitive name or numeric id and admits one attributed turn there.
 - During an active Telegram turn, answer the current target normally; direct delivery to that same target is rejected.
 - Direct delivery requires this Pi instance to own transport or hold a live Threaded Mode registration.