@volter/twin-telegram 1.0.0 → 1.0.1

package/journeys/customer-life.verdict.json

@@ -1,133 +1,59 @@
 {
   "judge": {
-    "agent": "Claude Code (Claude Agent SDK), model claude-opus-5-5",
-    "name": "Contributor 106"
+    "agent": "Claude journey judge (Opus)",
+    "name": "Independent journey judge"
   },
   "authors": [
-    "Contributor 173"
+    "yueranyuan",
+    "Aaron (A-001)",
+    "Claude Opus 5.5",
+    "Codex"
   ],
-  "bar": "829132787d94a2d4",
-  "sha256": "f58ee4db9e9c90c0f87f6018cf370f00963898ae16e0d4e7069e6afca17a6cf3",
-  "judgedAt": "2026-10-02",
+  "sha256": "d4f45ec531a3cafd7ec746629b2fb110cf5bb5adb0664f52a5d279eaf7f59ad3",
+  "judgedAt": "2026-10-15",
   "plausible": true,
   "rulings": [
     {
-      "id": "three-tuesdays-skipped",
+      "id": "reply-to-message-id-era",
       "steps": [
-        16,
-        20,
-        22,
-        30,
-        58,
-        62,
-        66,
-        70,
-        73
+        61
       ],
-      "barItem": "a stated cause that never happens, and a promise never kept",
-      "reason": "Steps 16, 20 and 22 set the standup for 9:00 every Tuesday, with items posted in the group, and the agent promises the digest at 9:15. From step 19 the agent is an administrator, and an administrator is sent every group message (https://core.telegram.org/bots/features#privacy-mode, \"bot admins always receive all messages\"). The job runs once, Tuesday 6 January (step 30). The team keeps the group standup until Monday 2 February (step 70: \"the standups move to a video call\"), yet Tuesdays 13, 20 and 27 January pass inside steps 58-70 with no items posted, no poll and no digest. Step 73's digest then says \"No standup items were posted this week\", which implies the earlier weeks had items. Three of the four weekly runs the story promises never happen, and nothing in the story explains why.",
-      "correction": "Move the standups' move and the bot's removal to Monday 12 January, 18:00, after step 61. The job's next run, Tuesday 13 January at 09:15, is then the refused one, and the waits to Wednesday 14 January 16:00 and onward are adjusted. Alternatively, show the Tuesday standups of 13, 20 and 27 January: items posted, a poll, and a digest each week."
+      "barItem": "the wrong era: building on an API the vendor had deprecated by the World's date; a call through a door the vendor does not document",
+      "reason": "Step 61 (Monday 12 January 2026) replies to the album with the form field reply_to_message_id={album}. Telegram replaced that parameter in Bot API 7.0, December 29, 2023 (https://core.telegram.org/bots/api-changelog: 'Replaced parameters reply_to_message_id and allow_sending_without_reply in the methods ... with the field reply_parameters'), and the page the spec is written from (https://core.telegram.org/bots/api#sendmessage, Bot API 10.3) no longer documents it; spec/SOURCE.md admits the page 'no longer lists it' and patches it in. A step through a parameter the vendor withdrew two years before the World's date is rejected even where the twin answers it.",
+      "correction": "Step 61 sends reply_parameters={\"message_id\":{album}} (JSON-serialized ReplyParameters, as https://core.telegram.org/bots/api#sendmessage documents) in place of reply_to_message_id, keeping its expectation result.reply_to_message.message_id equals {album}."
     },
     {
-      "id": "postiz-never-given-token-n",
+      "id": "photo-sizes-order",
       "steps": [
-        33,
-        37,
-        40,
-        41,
-        42,
-        43,
-        45,
-        46,
-        47,
-        48,
-        50,
         59,
-        61,
-        63,
-        65,
-        67,
         69
       ],
-      "barItem": "the wrong actor or credential for an act",
-      "reason": "Postiz's Telegram provider calls with one bot, the one its deployment configures: `new TelegramBot(process.env.TELEGRAM_TOKEN!)` (libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:19, postiz-app e0a08a7; demand.json, Postiz's client: \"TELEGRAM_TOKEN\"). In hosted Postiz, that is Postiz's own bot and not one a customer makes. Step 33 has Ana make @tidelabs_news_bot \"for Postiz\", and from step 37 on Postiz calls with {news_token}. But no step or name says that Ana runs Postiz herself, or that token N is set as its TELEGRAM_TOKEN. The life never shows how the credential Postiz uses reaches it, and as written it reads as the hosted product calling with a bot that belongs to the customer.",
-      "correction": "In step 33 or a step beside it, say that Ana runs Postiz herself (docker compose, local storage, as demand.json reads it) and sets TELEGRAM_TOKEN to the news bot's token before she adds Telegram. Use the same wording in the outline."
-    },
-    {
-      "id": "running-harness-polls-without-offset",
-      "steps": [
-        76
-      ],
-      "barItem": "content that does not bear out the step's name",
-      "reason": "Step 76 is Harness \"still running on her laptop\". The adapter it runs keeps its offset in its polling loop and sends it on every poll: `offset = update.update_id + 1` (@chat-adapter/telegram 4.39.0, dist/index.js:3327-3345, pollingLoop; demand.json: \"confirming the last with offset\"). The life last confirmed one at step 53. Step 76's body, {\"limit\": 100, \"timeout\": 30}, is the request a freshly started adapter sends (step 9), not the request of the process the step names.",
-      "correction": "Step 76's body: {\"offset\": \"{agent_next}\", \"limit\": 100, \"timeout\": 30}."
+      "barItem": "vendor behaviour the vendor's documentation contradicts",
+      "reason": "Step 59 expects result.0.photo.0.width 480 and result.2.photo.0.height 300 for 480x300 PNG uploads, and step 69 expects result.photo.0.width 640 and height 480 for a 640x480 JPEG: the first PhotoSize being the uploaded image itself. Telegram 'attaches a vector of thumbnails with reduced resolution to all uploaded media', the smallest type s 'bounded by 100x100 pixels' and m by 320x320 (https://core.telegram.org/api/files, image thumbnail types; Message.photo is 'available sizes of the photo', https://core.telegram.org/bots/api#message), and the Bot API answers them in ascending order (TDLib at 42e6a52, td/telegram/PhotoSize.cpp get_photo_sizes_object, stable_sort by size then width*height, the TDLib source the spec cites). photo.0 is the 100-pixel thumbnail; the original's dimensions are on the last size.",
+      "correction": "Steps 59 and 69 expect the uploaded dimensions on the last PhotoSize (step 59: result.0.photo.2.width 480 and result.2.photo.2.height 300; step 69: result.photo.2.width 640 and height 480), with photo.0 the s thumbnail, bounded by 100x100."
     }
   ],
   "applied": {
-    "from": "1248e944117c27955453a626f8ed5a44ff07ad520f525feaa0a7a6dc53399963",
+    "from": "8251bda4592d9f3dae1bb5067727bee657d212ebd5aca36c32e8a7f4d1beb222",
     "wasPlausible": false,
     "steps": [
-      "33",
-      "36",
-      "62",
-      "70",
-      "71",
-      "72",
-      "73",
-      "74",
-      "76"
+      "59",
+      "61",
+      "69"
     ],
     "rulings": [
       {
-        "id": "three-tuesdays-skipped",
         "steps": [
-          16,
-          20,
-          22,
-          30,
-          58,
-          62,
-          66,
-          70,
-          73
+          61
         ],
-        "barItem": "a stated cause that never happens, and a promise never kept",
-        "reason": "Steps 16, 20 and 22 set the standup for 9:00 every Tuesday, with items posted in the group, and the agent promises the digest at 9:15. From step 19 the agent is an administrator, and an administrator is sent every group message (https://core.telegram.org/bots/features#privacy-mode, \"bot admins always receive all messages\"). The job runs once, Tuesday 6 January (step 30). The team keeps the group standup until Monday 2 February (step 70: \"the standups move to a video call\"), yet Tuesdays 13, 20 and 27 January pass inside steps 58-70 with no items posted, no poll and no digest. Step 73's digest then says \"No standup items were posted this week\", which implies the earlier weeks had items. Three of the four weekly runs the story promises never happen, and nothing in the story explains why.",
-        "correction": "Move the standups' move and the bot's removal to Monday 12 January, 18:00, after step 61. The job's next run, Tuesday 13 January at 09:15, is then the refused one, and the waits to Wednesday 14 January 16:00 and onward are adjusted. Alternatively, show the Tuesday standups of 13, 20 and 27 January: items posted, a poll, and a digest each week."
+        "why": "Step 61 sends reply_parameters={\"message_id\":{album}} (JSON-serialized ReplyParameters, as https://core.telegram.org/bots/api#sendmessage documents) in place of reply_to_message_id, keeping its expectation result.reply_to_message.message_id equals {album}."
       },
       {
-        "id": "postiz-never-given-token-n",
         "steps": [
-          33,
-          37,
-          40,
-          41,
-          42,
-          43,
-          45,
-          46,
-          47,
-          48,
-          50,
           59,
-          61,
-          63,
-          65,
-          67,
           69
         ],
-        "barItem": "the wrong actor or credential for an act",
-        "reason": "Postiz's Telegram provider calls with one bot, the one its deployment configures: `new TelegramBot(process.env.TELEGRAM_TOKEN!)` (libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:19, postiz-app e0a08a7; demand.json, Postiz's client: \"TELEGRAM_TOKEN\"). In hosted Postiz, that is Postiz's own bot and not one a customer makes. Step 33 has Ana make @tidelabs_news_bot \"for Postiz\", and from step 37 on Postiz calls with {news_token}. But no step or name says that Ana runs Postiz herself, or that token N is set as its TELEGRAM_TOKEN. The life never shows how the credential Postiz uses reaches it, and as written it reads as the hosted product calling with a bot that belongs to the customer.",
-        "correction": "In step 33 or a step beside it, say that Ana runs Postiz herself (docker compose, local storage, as demand.json reads it) and sets TELEGRAM_TOKEN to the news bot's token before she adds Telegram. Use the same wording in the outline."
-      },
-      {
-        "id": "running-harness-polls-without-offset",
-        "steps": [
-          76
-        ],
-        "barItem": "content that does not bear out the step's name",
-        "reason": "Step 76 is Harness \"still running on her laptop\". The adapter it runs keeps its offset in its polling loop and sends it on every poll: `offset = update.update_id + 1` (@chat-adapter/telegram 4.39.0, dist/index.js:3327-3345, pollingLoop; demand.json: \"confirming the last with offset\"). The life last confirmed one at step 53. Step 76's body, {\"limit\": 100, \"timeout\": 30}, is the request a freshly started adapter sends (step 9), not the request of the process the step names.",
-        "correction": "Step 76's body: {\"offset\": \"{agent_next}\", \"limit\": 100, \"timeout\": 30}."
+        "why": "Steps 59 and 69 expect the uploaded dimensions on the last PhotoSize (step 59: result.0.photo.2.width 480 and result.2.photo.2.height 300; step 69: result.photo.2.width 640 and height 480), with photo.0 the s thumbnail, bounded by 100x100."
       }
     ]
   }

package/journeys/decisions.json

@@ -1,9 +1,9 @@
 {
- "about": "telegram's decision table (the P3 procedure: demand, then this table, then the code): each method the pack serves, the demand it answers (journeys/demand.json, or the manifest's refresh scope) and the mechanism that serves it. The Bot API is an RPC wire (POST /bot<token>/<method>, every answer {ok, result}), so no method is a create, read, update or delete the derived core could serve: each is a handler over the bot the token names (./src/semantics/around.ts resolves it, before routing, as the Bot API server does). Every other method of the page answers the server's unknown method (the manifest's gap), the URL-media sends only an opt-in Postiz storage makes (demand.json's optional) included: a URL the World cannot reach is refused as Telegram refuses one it cannot download. People, bots and chats are made through the World's doors (the Telegram app and BotFather, which no Bot API method stands for).",
+ "about": "telegram's decision table (the P3 procedure: demand, then this table, then the code): each method the pack serves, the demand it answers (journeys/demand.json, or the manifest's refresh scope) and the mechanism that serves it. The Bot API is an RPC wire (POST /bot<token>/<method>, every answer {ok, result}), so no method is a create, read, update or delete the derived core could serve: each is a handler over the bot the token names (./src/semantics/around.ts resolves it, before routing, as the Bot API server does). Every other method of the page answers the server's unknown method (the manifest's gap), the URL-media sends included: a URL the World cannot reach is refused as Telegram refuses one it cannot download. People, bots and chats are made through the World's doors (the Telegram app and BotFather, which no Bot API method stands for).",
  "decisions": [
   {
    "operation": "getMe",
-   "demand": "Volter Harness's adapter reads its bot as it starts; Postiz reads its bot's id when the /connect message is found",
+   "demand": "Volter Harness's adapter reads its bot as it starts",
    "mechanism": "handler",
    "why": "a computed read: the bot the token names, its User with the bot-only fields (can_join_groups, can_read_all_group_messages for privacy mode, supports_inline_queries, …)"
   },
@@ -15,7 +15,7 @@
   },
   {
    "operation": "getUpdates",
-   "demand": "Volter Harness's adapter polls in a loop (timeout 30, limit 100); Postiz's connect screen polls with allowed_updates [message, channel_post] and an offset",
+   "demand": "Volter Harness's adapter polls in a loop (timeout 30, limit 100)",
    "mechanism": "handler",
    "why": "an action: the bot's queue read from the offset (confirming, and so deleting, every update below it), filtered by the allowed_updates in force when each was made, at most limit; with nothing waiting and a timeout, the read held until an update is written (the kernel's held read)"
   },
@@ -27,7 +27,7 @@
   },
   {
    "operation": "sendMessage",
-   "demand": "Volter Harness posts its answers and its scheduled reports; Postiz posts a text (HTML), its connect notices and a comment as a reply",
+   "demand": "Volter Harness posts its answers and its scheduled reports",
    "mechanism": "handler",
    "why": "a message made in a chat the bot may write in: its message_id counted per chat, its text parsed for the parse_mode's entities (HTML, MarkdownV2 or Markdown), checked for length (1-4096 after parsing), a reply resolved; it writes no update for its own bot (bots do not receive their own messages)",
    "sourceRules": [
@@ -39,57 +39,93 @@
   },
   {
    "operation": "sendPhoto",
-   "demand": "Postiz posts one image with its caption (HTML), uploaded",
+   "demand": "No scanned application calls it; the customer life walks it.",
    "mechanism": "handler",
    "why": "a message with a photo: the upload's bytes stored as a file (its width and height read from the image), the caption parsed and checked (0-1024); a URL the World cannot reach is refused as the server refuses one it cannot download"
   },
   {
    "operation": "sendVideo",
-   "demand": "Postiz posts one video with its caption, uploaded",
+   "demand": "No scanned application calls it; the customer life walks it.",
    "mechanism": "handler",
    "why": "a message with a video: the bytes stored, its width, height and duration read from the file's own header where it is an MP4"
   },
   {
    "operation": "sendDocument",
-   "demand": "Postiz posts one file that is neither an image nor a video, uploaded; Volter Harness's board sends a done card's artifact with its notice as a MarkdownV2 caption",
+   "demand": "Volter Harness's board sends a done card's artifact with its notice as a MarkdownV2 caption",
    "mechanism": "handler",
    "why": "a message with a document: the bytes stored with its name and media type; its caption parsed as sendMessage's text is (HTML, MarkdownV2 or Markdown) and checked (0-1024)"
   },
   {
    "operation": "sendMediaGroup",
-   "demand": "Postiz posts several images or videos as one album, the caption on the first, uploaded (attach://<name>); Volter Harness's board sends a done card's several artifacts as one album of documents",
+   "demand": "Volter Harness's board sends a done card's several artifacts as one album of documents",
    "mechanism": "handler",
    "why": "2-10 messages sharing one media_group_id, each its own file; the array of sent messages answered"
   },
   {
    "operation": "deleteMessage",
-   "demand": "Postiz deletes the /connect message and its own success notice",
+   "demand": "No scanned application calls it; the customer life walks it.",
    "mechanism": "handler",
    "why": "a message deleted where the bot may delete it: its own, or another's in a channel or group where it is an administrator with can_delete_messages; 'message to delete not found' for one that is not there"
   },
   {
    "operation": "getChat",
-   "demand": "Postiz reads the channel it is connecting (id, title, username, photo); the vendor-backed refresh reads each chat again (the manifest's refresh of chat)",
+   "demand": "the vendor-backed refresh reads each chat again (the manifest's refresh of chat)",
    "mechanism": "handler",
    "why": "a computed read: the chat as ChatFullInfo, its access checked as the server checks a read"
   },
   {
    "operation": "getChatMember",
-   "demand": "Postiz checks its bot is an administrator that can delete messages in the channel",
+   "demand": "No scanned application calls it; the customer life walks it.",
    "mechanism": "handler",
    "why": "a computed read: the member's status and rights with its user"
   },
   {
    "operation": "getFile",
-   "demand": "Postiz reads the chat photo's file to make its link",
+   "demand": "No scanned application calls it; the customer life walks it.",
    "mechanism": "handler",
    "why": "an action: the file's download path issued (file_path), valid for the bot that asked"
   },
   {
    "operation": "downloadFile",
-   "demand": "Postiz copies the chat photo into its storage from the file's link",
+   "demand": "No scanned application calls it; the customer life walks it.",
    "mechanism": "handler",
    "why": "the stored bytes of the file a getFile path names, for the bot whose token is in the path"
+  },
+  {
+   "operation": "door:people",
+   "demand": "the World's own door, POST /_twin/people: { first_name, last_name?, username?, language_code? }: a Telegram account, as a person signs up in the app",
+   "mechanism": "door",
+   "why": "{ first_name, last_name?, username?, language_code? }: a Telegram account, as a person signs up in the app, which no vendor API makes."
+  },
+  {
+   "operation": "door:bots",
+   "demand": "the World's own door, POST /_twin/bots: { owner?, name?, username? }: BotFather's /newbot, for the person `owner` (a user id): the bot and its token; the same username answers the same bot",
+   "mechanism": "door",
+   "why": "{ owner?, name?, username? }: BotFather's /newbot, for the person `owner` (a user id): the bot and its token; the same username answers the same bot, which no vendor API makes."
+  },
+  {
+   "operation": "door:botToken",
+   "demand": "the World's own door, POST /_twin/bots/{username}/token: { owner }: BotFather's /token: a new token, the old one revoked",
+   "mechanism": "door",
+   "why": "{ owner }: BotFather's /token: a new token, the old one revoked, which no vendor API makes."
+  },
+  {
+   "operation": "door:chats",
+   "demand": "the World's own door, POST /_twin/chats: { creator, type: group | supergroup | channel, title, username?, description?, photo? (base64 bytes), members?: [{ user, status?: member | administrator, rights? }] }: a person makes a chat in the app",
+   "mechanism": "door",
+   "why": "{ creator, type: group | supergroup | channel, title, username?, description?, photo? (base64 bytes), members?: [{ user, status?: member | administrator, rights? }] }: a person makes a chat in the app, which no vendor API makes."
+  },
+  {
+   "operation": "door:members",
+   "demand": "the World's own door, POST /_twin/chats/{chat_id}/members: { by, user, status: member | administrator | kicked, rights? }: a person adds, promotes or removes a member in the app",
+   "mechanism": "door",
+   "why": "{ by, user, status: member | administrator | kicked, rights? }: a person adds, promotes or removes a member in the app, which no vendor API makes."
+  },
+  {
+   "operation": "door:messages",
+   "demand": "the World's own door, POST /_twin/messages: { from, chat (a chat id, a chat's @username, or a bot's @username for a private chat with it), text, reply_to_message_id? }: a person writes in the app",
+   "mechanism": "door",
+   "why": "{ from, chat (a chat id, a chat's @username, or a bot's @username for a private chat with it), text, reply_to_message_id? }: a person writes in the app, which no vendor API makes."
   }
  ]
 }

package/journeys/demand.json

@@ -55,97 +55,6 @@
           "client": "@chat-adapter/telegram@4.39.0:dist/index.js:2802"
         }
       ]
-    },
-    {
-      "commit": "e0a08a7d9592fdc1ef1e82cb7cb781489fceade3",
-      "client": "node-telegram-bot-api 0.66.0 (POST https://api.telegram.org/bot<token>/<method>, form-urlencoded, multipart for a file; rows marked node-telegram-bot-api@0.66.0: are its published src), TELEGRAM_TOKEN",
-      "backend": [
-        {
-          "call": "the connect screen polls for the person's /connect message (allowed_updates message and channel_post, from the last offset)",
-          "operation": "getUpdates",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:87",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:849"
-        },
-        {
-          "call": "found: the bot's own id",
-          "operation": "getMe",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:105",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:931"
-        },
-        {
-          "call": "...whether it is an administrator that can delete messages there",
-          "operation": "getChatMember",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:356",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1966"
-        },
-        {
-          "call": "an administrator: the /connect message deleted, a success notice posted and deleted ten seconds later",
-          "operation": "deleteMessage",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:120",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:3093"
-        },
-        {
-          "call": "the success notice (or, without the right to delete, the notice asking the person to remove the messages)",
-          "operation": "sendMessage",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:122",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:970"
-        },
-        {
-          "call": "the channel added: its chat read (id, title, username, photo)",
-          "operation": "getChat",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:62",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1924"
-        },
-        {
-          "call": "...and its photo's file, whose path makes the channel's picture link",
-          "operation": "getFile",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:71",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1522"
-        },
-        {
-          "call": "...and Postiz copies the picture into its own storage from that link",
-          "operation": "downloadFile",
-          "evidence": "libraries/nestjs-libraries/src/database/prisma/integrations/integration.service.ts:119",
-          "client": "libraries/nestjs-libraries/src/upload/local.storage.ts:62"
-        },
-        {
-          "call": "a post with no media: its text, parse_mode HTML",
-          "operation": "sendMessage",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:224",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:970"
-        },
-        {
-          "call": "a post with one image: the photo uploaded with the text as its caption",
-          "operation": "sendPhoto",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:247",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1075"
-        },
-        {
-          "call": "a post with one video",
-          "operation": "sendVideo",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:240",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1164"
-        },
-        {
-          "call": "a post with one file that is neither",
-          "operation": "sendDocument",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:253",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1136"
-        },
-        {
-          "call": "a post with several media: an album of up to ten, the text on the first",
-          "operation": "sendMediaGroup",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:272",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1296"
-        },
-        {
-          "call": "a comment: the next post sent as a reply to the last (reply_to_message_id)",
-          "operation": "sendMessage",
-          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:226",
-          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:970"
-        }
-      ],
-      "name": "gitroomhq/postiz-app"
     }
   ],
   "optional": []

package/journeys/first-use.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "source": "https://chat-sdk.dev/docs/adapters/telegram",
+  "about": "Volter Harness's Telegram channel as it ships (supercode 62620578c014, sdk/orchestrator/adapters/chat-sdk.mjs): the unchanged Chat SDK (chat 4.39.0, @chat-adapter/telegram 4.39.0, @chat-adapter/state-memory 4.39.0) polls with the bot token the World's credential door issues as TELEGRAM_BOT_TOKEN (getMe, deleteWebhook, getUpdates), hears Ada's private message (the World's people and messages doors stand in for the Telegram app) and answers in her chat (thread.post: sendMessage). The readback reads her private chat back (getChat) without polling or sending.",
+  "files": {
+    "package.json": "{\n  \"name\": \"telegram-harness-customer\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"chat\": \"4.39.0\",\n    \"@chat-adapter/telegram\": \"4.39.0\",\n    \"@chat-adapter/state-memory\": \"4.39.0\"\n  }\n}\n",
+    ".env.example": "TELEGRAM_BOT_TOKEN=\nTELEGRAM_BOT_USERNAME=\n",
+    "agent.mjs": "import assert from 'node:assert/strict';\nimport { readFileSync, writeFileSync } from 'node:fs';\nimport { Chat } from 'chat';\nimport { createTelegramAdapter } from '@chat-adapter/telegram';\nimport { createMemoryState } from '@chat-adapter/state-memory';\nif (!process.env.VOLTER_WORLD) throw new Error('Run this app through its World.');\n// Volter Harness's Telegram channel: the Chat SDK's adapter from TELEGRAM_BOT_TOKEN, polling (sdk/orchestrator/adapters/chat-sdk.mjs)\nconst telegram = createTelegramAdapter({ botToken: process.env.TELEGRAM_BOT_TOKEN, mode: 'polling', logger: console });\nconst receiptFile = 'telegram-chat.json';\nif (process.argv[2] === 'readback') {\n  const saved = JSON.parse(readFileSync(receiptFile, 'utf8'));\n  const thread = await telegram.fetchThread(saved.thread);\n  assert.equal(thread.id, saved.thread);\n  assert.equal(thread.isDM, true);\n  assert.equal(thread.metadata.chat.first_name, 'Ada');\n  console.log(JSON.stringify({ retained: true, thread: thread.id, chat: thread.metadata.chat }));\n} else {\n  // Ada opens the bot in the Telegram app and writes to it: the World's doors stand in for the app\n  const api = (process.env.TELEGRAM_API_BASE_URL ?? 'https://api.telegram.org').replace(/\\/+$/, '');\n  const door = async (path, body) => {\n    const response = await fetch(api + path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });\n    if (!response.ok) throw new Error(path + ' was refused: ' + response.status + ' ' + await response.text());\n    return response.json();\n  };\n  const ada = await door('/_twin/people', { first_name: 'Ada', username: 'ada_lovelace' });\n  await door('/_twin/messages', { from: ada.id, chat: '@' + process.env.TELEGRAM_BOT_USERNAME, text: 'Hi! Can you keep notes of our standups?' });\n  const answered = new Promise((resolve, reject) => {\n    const chat = new Chat({ adapters: { telegram }, state: createMemoryState(), concurrency: 'concurrent', logger: 'silent' });\n    chat.onDirectMessage(async (thread, message) => {\n      try {\n        const sent = await thread.post('Noted, Ada: I will keep the standup notes here.');\n        resolve({ chat, thread, message, sent });\n      } catch (error) { reject(error); }\n    });\n    chat.initialize().catch(reject);\n  });\n  const { chat, thread, message, sent } = await answered;\n  await telegram.stopPolling();\n  await chat.shutdown();\n  assert.equal(thread.isDM, true);\n  assert.equal(message.text, 'Hi! Can you keep notes of our standups?');\n  assert.equal(message.author.userId, String(ada.id));\n  assert.equal(message.author.isMe, false);\n  assert.equal(thread.id, 'telegram:' + ada.id);\n  assert.match(String(sent.id), new RegExp('^' + ada.id + ':\\\\d+$'), 'the answer names the message Telegram gave it in her chat');\n  assert.equal(sent.text, 'Noted, Ada: I will keep the standup notes here.');\n  writeFileSync(receiptFile, JSON.stringify({ thread: thread.id, message: sent.id }) + '\\n');\n  console.log(JSON.stringify({ answered: true, thread: thread.id, heard: message.text, sent: sent.id }));\n}\n"
+  },
+  "run": [
+    "node",
+    "agent.mjs"
+  ],
+  "retention": {
+    "readback": [
+      "node",
+      "agent.mjs",
+      "readback"
+    ]
+  }
+}

package/journeys/unreachable.json

@@ -22,7 +22,7 @@
     "urlUnreachable"
    ],
    "world": "sealed-refusal",
-   "why": "A photo, video or document sent by an HTTP URL is downloaded by Telegram; a World is sealed, so the twin reaches no URL outside it and answers Telegram's failure for a URL it cannot get. No World of this surface replays the download (spec/doc-examples.json's sendPhoto: an HTTP URL is recorded not replayed for the same reason), and the only application that sends URLs is Postiz with its opt-in Cloudflare storage (journeys/demand.json, optional)."
+   "why": "A photo, video or document sent by an HTTP URL is downloaded by Telegram; a World is sealed, so the twin reaches no URL outside it and answers Telegram's failure for a URL it cannot get. No World of this surface replays the download (spec/doc-examples.json's sendPhoto: an HTTP URL is recorded not replayed for the same reason)."
   }
  ],
  "state": []

package/journeys/vendor-examples.json

@@ -1221,12 +1221,20 @@
    },
    "status": 200,
    "capture": {
-    "notes_photo": "result.photo.0.file_id",
-    "notes_unique": "result.photo.0.file_unique_id"
+    "notes_photo": "result.photo.1.file_id",
+    "notes_unique": "result.photo.1.file_unique_id"
    },
    "expect": [
     {
-     "path": "result.photo.1",
+     "path": "result.photo.0.width",
+     "equals": 100
+    },
+    {
+     "path": "result.photo.1.width",
+     "equals": 320
+    },
+    {
+     "path": "result.photo.2",
      "exists": false
     }
    ]
@@ -1242,15 +1250,15 @@
    },
    "status": 200,
    "undecided": {
-    "result.photo.0.file_id": "a resent file may answer another valid file_id; the twin answers the one sent, which only coincides (Sending files: \"a file can have different valid file_ids even for the same bot\")"
+    "result.photo.1.file_id": "a resent file may answer another valid file_id; the twin answers the one sent, which only coincides (Sending files: \"a file can have different valid file_ids even for the same bot\")"
    },
    "expect": [
     {
-     "path": "result.photo.0.file_unique_id",
+     "path": "result.photo.1.file_unique_id",
      "equals": "{notes_unique}"
     },
     {
-     "path": "result.photo.1",
+     "path": "result.photo.2",
      "exists": false
     },
     {

package/package.json

@@ -1,37 +1,40 @@
 {
   "name": "@volter/twin-telegram",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "The telegram twin (Protocol 3).",
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/src/index.d.ts",
-      "default": "./dist/src/index.js"
-    }
+    ".": "./dist/src/index.js"
   },
   "bin": {
     "world-telegram": "dist/src/cli.js"
   },
   "files": [
+    "dist",
+    "generated",
     "src",
     "journeys",
     "spec",
     "README.md",
     "!**/*.test.ts",
-    "dist",
-    "generated"
+    "LICENSE"
   ],
   "peerDependencies": {
-    "@volter/world-core": "^3.0.38"
+    "@volter/world-core": ">=3.0.164",
+    "@volter/world-runtime": ">=3.0.184"
   },
   "engines": {
     "node": ">=22.3"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/volter-ai/twin-packs-p3.git",
+    "url": "git+https://github.com/volter-ai/twin-packs-open.git",
     "directory": "telegram"
+  },
+  "homepage": "https://github.com/volter-ai/twin-packs-open/tree/main/telegram#readme",
+  "bugs": {
+    "url": "https://github.com/volter-ai/twin-packs-open/issues"
   }
 }

package/spec/SOURCE.md

@@ -4,15 +4,14 @@
   from its reference page, https://core.telegram.org/bots/api, as Telegram serves it (fetched 2026-10-02, HTML,
   860074 bytes, sha256 `9da688c4213864d7911fcf0f501d2d7a8c3bbc351b8b4325e85e509bcc9d969f`; the page's "Recent changes"
   head it **Bot API 10.3**, August 24, 2026).
-- **How it was written:** mechanically from the page's HTML by `page-to-openapi.ts`, kept here
-  (`gunzip -c spec/bot-api.html.gz > page.html; bun spec/page-to-openapi.ts page.html openapi.json`, then `gzip -n -9`), from the bytes named above, kept here as `bot-api.html.gz`, every
-  section of methods and types it documents (Getting updates, Available types, Available methods, Updating messages,
-  Stickers, Rich messages, Inline mode, Payments, Telegram Passport, Games): 185 methods and 400 types.
+- **How it was written:** mechanically from the page's HTML, captured as `bot-api.html.gz` with the bytes named above.
+  It covers the page's methods and types across Getting updates, Available types, Available methods, Updating messages,
+  Stickers, Rich messages, Inline mode, Payments, Telegram Passport and Games: 185 methods and 400 types.
   - A method (an `h4` with a lower-case name and a Parameter/Type/Required/Description table) is
     `POST /bot{token}/<method>` (the page's "https://api.telegram.org/bot<token>/METHOD_NAME"), its operationId the
     method's name, its tag the page's section; its parameters a body taken as JSON, form or multipart, and the same
     parameters again in the query string, none required there (the page's "four ways of passing parameters", the
-    first of them the URL query string: Postiz's node-telegram-bot-api sends a medium's chat_id and caption in the
+    first of them the URL query string: node-telegram-bot-api sends a medium's chat_id and caption in the
     query beside its multipart file), `Required: Yes` required in the body; its answer `{ ok: true, result }` with the result the
     method's text says is returned (a linked type, "Array of", True, String or Integer; several, `oneOf`), and any
     other answer the error envelope `{ ok: false, error_code, description, parameters? }` (Making requests).
@@ -35,7 +34,7 @@
 - **Corrections:** `patches.json` (RFC 6902, each with its reason and source): `reply_to_message_id` added to the
   bodies and the query parameters of sendMessage, sendPhoto, sendVideo, sendDocument and sendMediaGroup. The page no longer lists it, but the Bot
   API server still reads it when a request carries no `reply_parameters` (tdlib/telegram-bot-api, Client.cpp at
-  e3e9dd8), and node-telegram-bot-api 0.66.0, as Postiz calls it, sends it.
+  e3e9dd8), and node-telegram-bot-api 0.66.0 sends it.
 - **Grouping:** `grouping.json` (`{ "by": "tag" }`): every path begins `/bot{token}/`, so an operation's family is the
   page's section it is documented in.
 - **Other sources read:** the Bot API server's own source, which the page names ("Using a Local Bot API Server"),