appback-remoteagent 0.13.0

package/dist/telegram-fetch.js

@@ -0,0 +1,85 @@
+import http from "node:http";
+import https from "node:https";
+import { URL } from "node:url";
+function normalizeBody(body) {
+    if (body == null) {
+        return undefined;
+    }
+    if (typeof body === "string") {
+        return Buffer.from(body, "utf8");
+    }
+    if (body instanceof URLSearchParams) {
+        return Buffer.from(body.toString(), "utf8");
+    }
+    if (Buffer.isBuffer(body)) {
+        return body;
+    }
+    if (ArrayBuffer.isView(body)) {
+        return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+    }
+    if (body instanceof ArrayBuffer) {
+        return Buffer.from(body);
+    }
+    throw new TypeError("Unsupported fetch body type.");
+}
+export async function telegramFetch(input, init) {
+    const target = new URL(typeof input === "string"
+        ? input
+        : input instanceof URL
+            ? input.toString()
+            : input.url);
+    const requestInit = init ?? {};
+    const method = requestInit.method ?? (input instanceof Request ? input.method : "GET");
+    const headers = new Headers(input instanceof Request ? input.headers : undefined);
+    if (requestInit.headers) {
+        const extra = new Headers(requestInit.headers);
+        extra.forEach((value, key) => headers.set(key, value));
+    }
+    const rawBody = requestInit.body ?? (input instanceof Request ? await input.arrayBuffer() : undefined);
+    const body = normalizeBody(rawBody);
+    if (body && !headers.has("content-length")) {
+        headers.set("content-length", String(body.byteLength));
+    }
+    return await new Promise((resolve, reject) => {
+        const client = target.protocol === "http:" ? http : https;
+        const req = client.request(target, {
+            method,
+            headers: Object.fromEntries(headers.entries()),
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            });
+            res.on("end", () => {
+                const responseHeaders = new Headers();
+                for (const [key, value] of Object.entries(res.headers)) {
+                    if (Array.isArray(value)) {
+                        responseHeaders.set(key, value.join(", "));
+                    }
+                    else if (value !== undefined) {
+                        responseHeaders.set(key, value);
+                    }
+                }
+                resolve(new Response(Buffer.concat(chunks), {
+                    status: res.statusCode ?? 500,
+                    statusText: res.statusMessage ?? "",
+                    headers: responseHeaders,
+                }));
+            });
+        });
+        req.on("error", reject);
+        if (requestInit.signal) {
+            if (requestInit.signal.aborted) {
+                req.destroy(new Error("The operation was aborted."));
+                return;
+            }
+            requestInit.signal.addEventListener("abort", () => {
+                req.destroy(new Error("The operation was aborted."));
+            }, { once: true });
+        }
+        if (body) {
+            req.write(body);
+        }
+        req.end();
+    });
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/ARCHITECTURE.md

@@ -0,0 +1,170 @@
+# Architecture
+
+## Intent
+
+RemoteAgent is a personal installable runtime for six primary jobs:
+
+1. Telegram control
+2. terminal control
+3. Telegram to Codex session continuity
+4. Telegram to Claude Code session continuity
+5. Telegram attachment intake for images, documents, and related files
+6. Telegram Mini App UI over the same runtime state
+
+The runtime machine is the source of truth.
+Telegram is a client of that runtime, not the owner of the session state.
+The Mini App is a richer client of the same runtime, not a separate backend.
+
+## Core principles
+
+1. One owner, one runtime, local control.
+2. Sessions belong to the local runtime.
+3. Telegram chat is a remote control surface over those sessions.
+4. A Telegram Mini App is an optional structured UI over the same sessions.
+5. Codex and Claude Code are adapters behind a shared local session model.
+6. Terminal control is gated and attached to runtime-owned session state.
+7. Telegram attachments are materialized locally before provider routing.
+8. Process ownership must remain single-instance and deterministic.
+
+## System shape
+
+```text
+Telegram chat client                  Telegram Mini App UI
+        \                                   /
+         \                                 /
+          -> RemoteAgent runtime on the owner machine
+               -> session store
+               -> chat/session bindings
+               -> event logs
+               -> attachment store
+               -> provider router
+               -> owner-only terminal gateway
+               -> Codex adapter
+               -> Claude Code adapter
+               -> future providers
+```
+
+## Main subsystems
+
+### Telegram control layer
+
+Responsibilities:
+
+- accept Telegram commands and messages
+- bind chats to runtime sessions
+- expose status/list/switch/reset flows
+- accept attachments and route them to the active session
+- gate privileged commands such as remote shell
+
+### Telegram Mini App layer
+
+Responsibilities:
+
+- present the same sessions in a richer UI
+- expose session lists, status, logs, and actions without relying on raw slash commands
+- submit structured actions back to the runtime server
+- stay thin: no provider execution, no separate session source of truth
+
+### Session layer
+
+Responsibilities:
+
+- own RemoteAgent session ids
+- persist workspace metadata
+- track provider bindings
+- record append-only event history
+- serialize work per session when needed
+
+### Provider adapter layer
+
+Responsibilities:
+
+- start or continue provider sessions
+- translate runtime requests into provider-specific commands
+- store provider session identifiers such as Codex `thread_id` and Claude `session_id`
+- return normalized outputs back to the runtime
+
+### Terminal control layer
+
+Responsibilities:
+
+- execute owner-only shell commands in the active workspace
+- enforce private-chat and owner-only restrictions
+- keep terminal access tied to Codex danger-full-access mode
+
+### Attachment layer
+
+Responsibilities:
+
+- download Telegram-hosted files
+- store them under runtime-owned local paths
+- build attachment prompts for the active provider flow
+- keep internal runtime paths out of user-facing responses where possible
+
+## Provider support today
+
+| Provider | Current state | Resume identifier | Notes |
+| --- | --- | --- | --- |
+| Codex | Implemented | `thread_id` | Supports Telegram sandbox control and remote-shell gating |
+| Claude Code | Implemented | `session_id` | Supports attach/resume through the same runtime model |
+| OpenClaw | Planned | TBD | Not yet implemented |
+
+## Mini App role
+
+The Mini App should be treated as a control-plane UI for an already-installed runtime.
+
+It is not:
+
+- a replacement for the runtime server
+- a hosted multi-tenant backend
+- a place where provider CLIs run directly
+
+It is:
+
+- a Telegram-native web UI
+- an easier way to view and manage sessions
+- a better surface for logs, buttons, state, and attachments
+- a future replacement for some slash-command-heavy workflows
+
+## Operational constraints
+
+The runtime must behave as a single owned process.
+
+That means:
+
+- `systemd` owns the production runtime on server 30
+- ad hoc duplicate `node dist/index.js` processes must not coexist
+- stale PID and stale lock state must not become the effective source of truth
+- image and attachment incidents must be debugged against one live process generation, not many
+
+The production operating rules are documented in [OPERATIONS.md](./OPERATIONS.md).
+
+## Current status
+
+Stable today:
+
+- Telegram control
+- owner-only terminal control
+- Telegram <-> Codex session handling
+- Telegram <-> Claude Code session handling
+- Telegram attachment download and local materialization
+- single-instance runtime locking on server 30
+
+Planned next:
+
+- Telegram Mini App UI over existing runtime state
+- structured session controls in Telegram beyond slash commands
+- richer attachment and log inspection UX
+
+Still improving:
+
+- attachment response policy and user-facing output quality
+- broader inspection and debugging UX
+- future local PC chat UI maturity
+
+## Non-goals
+
+- hosted multi-tenant control plane
+- account pooling or resale
+- pretending RemoteAgent is the official Codex or Claude desktop product
+- treating Telegram itself as the execution backend

package/docs/COKACDIR_NOTES.md

@@ -0,0 +1,79 @@
+# COKACDIR Notes
+
+## What was referenced
+
+`cokacdir` was used as a reference point for product shape, not as a codebase to mirror exactly.
+
+The useful high-level ideas are:
+
+- installable owner-run runtime
+- Telegram as a remote control surface for an existing coding agent
+- no separate hosted AI backend required
+- local session persistence
+- strong operator tooling around logs, processes, and files
+
+## What `cokacdir` appears to optimize for
+
+From its public README and local repository layout, `cokacdir` is broader than RemoteAgent.
+It combines:
+
+- Telegram bot control
+- multi-provider execution
+- terminal/file manager style tooling
+- process management
+- SSH/SFTP and other power-user utilities
+- a larger installable desktop/runtime surface
+
+That is a different product envelope from RemoteAgent.
+
+## What RemoteAgent should borrow
+
+The main lessons worth borrowing are operational, not cosmetic:
+
+1. one installable runtime per owner
+2. stable local state directories
+3. explicit environment-driven configuration
+4. practical operator commands for logs, status, and process control
+5. Telegram as a client of the runtime, not the source of truth
+
+## What RemoteAgent should not copy blindly
+
+RemoteAgent is intentionally narrower.
+It should not drift into a giant terminal/file-manager product just because `cokacdir` supports that.
+
+RemoteAgent should stay focused on:
+
+- personal session runtime
+- Codex/Claude style provider adapters
+- Telegram and future local chat UI over the same session model
+- predictable session/workspace ownership
+- safe process lifecycle
+
+## Key difference in current implementation
+
+A critical design decision for RemoteAgent is:
+
+- server 30 is the canonical runtime for `codex_remoteagent_bot`
+- local machine 21 is separate for `sqream_bot`
+- runtime ownership matters more than chat UX convenience
+
+This means RemoteAgent must care deeply about:
+
+- which machine owns the provider session
+- where the workspace actually lives
+- where the runtime state is stored
+- which exact process is answering Telegram
+
+That last point became important during the image-send incident.
+The bug felt like an attachment bug, but the root problem was that multiple runtime generations could coexist.
+
+## Current conclusion
+
+`cokacdir` is a useful reference for the installable Telegram-controlled agent idea.
+But RemoteAgent should keep its own simpler model:
+
+```text
+Telegram/local UI -> single local runtime -> provider adapters -> local sessions/workspaces
+```
+
+The value is continuity across the owner's own machines and sessions, not reproducing every feature from a broader terminal product.

package/docs/ERROR_NORMALIZATION.md

@@ -0,0 +1,46 @@
+# Error Normalization
+
+RemoteAgent should never leak raw provider event payloads directly to Telegram users.
+
+## Goals
+
+- normalize provider failures into stable user-facing messages
+- classify retryable vs non-retryable failures
+- keep internal details in logs, not in Telegram replies
+- make retry behavior predictable for long-running Telegram sessions
+- tell users when a retryable issue is being retried and when automatic retries stop
+
+## Current retryable classes
+
+- `provider.capacity.retryable`
+  - example: `Selected model is at capacity`
+  - behavior: send a progress-style retry notice, wait, retry automatically
+- `provider.empty_response.retryable`
+  - example: provider returned no usable final text after progress
+  - behavior: send a progress-style retry notice, wait, retry automatically
+- `provider.timeout.final`
+  - example: `Codex timed out after 600s without returning a final reply`
+  - behavior: do not retry automatically; explain the exact configured timeout that killed the provider process
+
+## Current terminal behavior
+
+When retries are exhausted:
+
+- capacity -> say the selected model is at capacity, then ask the user to retry later or switch models
+- empty response -> explain that automatic continuation stopped after repeated empty follow-up replies
+
+When a provider process reaches `COMMAND_TIMEOUT_MS`:
+
+- report that the provider process exceeded the configured execution timeout
+- do not say only that "response was delayed"
+- do not invent a cause such as context compaction, provider outage, or model quality unless the provider output explicitly says that
+- tell the operator to increase `/option timeout <seconds>` for long-running work
+
+## Maintenance rule
+
+When a new provider error shape appears:
+
+1. capture the raw provider output in logs
+2. add a stable classifier
+3. map it to a retry policy or a final user-facing message
+4. keep raw JSON and internal event envelopes out of Telegram replies

package/docs/MINI_APP.md

@@ -0,0 +1,112 @@
+# Telegram Mini App Plan
+
+## Positioning
+
+RemoteAgent should treat a Telegram Mini App as a richer control UI for the same installable runtime.
+
+It should not be described as:
+
+- a standalone hosted app
+- a replacement for the runtime server
+- a separate agent execution environment
+
+It should be described as:
+
+- a Telegram-native web UI
+- an optional control plane for the installed runtime
+- a structured companion to the existing Telegram bot chat
+
+## Why it fits RemoteAgent
+
+RemoteAgent already has:
+
+- Telegram bot identity and chat entry points
+- persisted sessions
+- session switching
+- provider metadata
+- stop and continue controls
+- attachment history
+- event logs
+
+A Mini App can expose those features more clearly than raw commands.
+
+## First MVP
+
+The first Mini App should focus on runtime visibility and control, not on replacing chat.
+
+### MVP screens
+
+1. Session list
+   - public session id
+   - provider mode
+   - workspace label
+   - updated time
+
+2. Session detail
+   - current provider
+   - model
+   - sandbox state
+   - workspace path summary
+   - provider binding state
+
+3. Activity view
+   - recent event log items
+   - progress/result/blocked states
+   - attachment entries
+
+4. Actions
+   - switch session
+   - continue
+   - stop
+   - new session
+   - reset binding
+
+## Runtime boundary
+
+The Mini App should call runtime-owned APIs.
+It should not directly execute Codex, Claude Code, or shell commands on its own.
+
+The runtime remains responsible for:
+
+- provider execution
+- session storage
+- authorization
+- attachment download and send
+- error normalization
+
+## Authentication model
+
+The Mini App should trust Telegram launch context only as an input signal.
+Runtime-side checks still matter.
+
+Expected checks:
+
+- Telegram user id matches `TELEGRAM_OWNER_ID` for privileged actions
+- current bot/chat context maps to the expected runtime channel
+- action is valid for the target session
+
+## Suggested rollout
+
+### Phase 1
+
+- menu button launches Mini App
+- read-only session list and session detail
+- stop and continue buttons
+
+### Phase 2
+
+- attachment history
+- structured model selection
+- better progress log browsing
+
+### Phase 3
+
+- richer batch composition
+- per-session settings views
+- safer admin flows for bot/runtime management
+
+## Non-goals
+
+- replacing Telegram chat entirely
+- multi-user SaaS dashboard
+- separate hosted control plane detached from the runtime machine

package/docs/MVP.md

@@ -0,0 +1,108 @@
+# MVP
+
+## Objective
+
+The MVP is a usable personal runtime that proves five things together:
+
+1. Telegram can control the runtime
+2. the owner can use terminal control safely
+3. Telegram can continue Codex work
+4. Telegram can continue Claude Code work
+5. Telegram can pass images and documents into the active session flow
+
+Success means the owner can work on their machine, continue from Telegram, and return without losing the local runtime context.
+
+## Product boundary
+
+This MVP is for:
+
+- one owner
+- one installable local runtime
+- personal provider credentials
+- local state only
+
+This MVP is not for:
+
+- hosted SaaS
+- external users
+- team billing or org management
+- account sharing
+
+## MVP pillars
+
+### 1. Telegram control
+
+Minimum requirements:
+
+- create or bind a local session from Telegram
+- inspect status
+- switch sessions
+- reset a chat binding
+- send normal Telegram text messages into the active provider session
+
+### 2. Terminal control
+
+Minimum requirements:
+
+- run shell commands from Telegram
+- keep this owner-only
+- keep this private-chat-only
+- tie dangerous shell access to the current Codex sandbox policy
+
+### 3. Codex integration
+
+Minimum requirements:
+
+- start a fresh Codex pairing
+- attach to an existing Codex `thread_id`
+- continue the same Codex session across turns
+- keep workspace metadata with the session
+
+### 4. Claude Code integration
+
+Minimum requirements:
+
+- start a fresh Claude pairing
+- attach to an existing Claude `session_id`
+- continue the same Claude session across turns
+- keep workspace metadata with the session
+
+### 5. Attachment intake
+
+Minimum requirements:
+
+- accept Telegram photos and supported files
+- materialize them locally in runtime-owned storage
+- route them through the active session flow
+- avoid leaking internal local paths in normal user-facing replies when possible
+
+## Supporting runtime requirements
+
+To make the five pillars actually usable, the runtime also needs:
+
+- local session persistence
+- provider binding persistence
+- append-only event logs
+- stable runtime-owned session ids
+- deterministic single-instance process ownership
+- recoverable restart behavior
+
+## Acceptance criteria
+
+The MVP is done when all of the following are true:
+
+1. Telegram can control a local runtime session reliably.
+2. Terminal control works under explicit restrictions.
+3. Codex can be paired or attached from Telegram.
+4. Claude Code can be paired or attached from Telegram.
+5. Telegram image/document inputs reach the active session flow.
+6. Restarts do not create ambiguous multi-process ownership.
+7. Session state survives process restarts.
+
+## Explicit non-goals
+
+- hosted sync service
+- public multi-user bot service
+- account resale
+- exact parity with official desktop apps
+- turning RemoteAgent into a general-purpose terminal file manager