# palomo1632-prog/agente-dsh architecture

> Architecture diagram of the GitHub repository palomo1632-prog/agente-dsh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/palomo1632-prog/agente-dsh
- Repository: https://github.com/palomo1632-prog/agente-dsh

## Overview

Agente DSH is a VPS-hosted coding agent exposed through a Telegram plugin. The main interaction is Telegram update → access and routing → command, interactive response, or media-enriched prompt → harness session → streamed reply. The plugin also supports approvals and questions as chat buttons, voice and image intake, session/model controls, and Telegram polling and messaging. The graph focuses on the sampled plugin runtime; several feature nodes use exact tree paths but their internal connections are left out where source was not shown.

Main entry points: [`plugins/dsh-telegram/lib/router.js`](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/router.js) (Update router), [`plugins/dsh-telegram/lib/session/runner.js`](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/session/runner.js) (Session runner), [`plugins/dsh-telegram/lib/media/collect.js`](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/media/collect.js) (Media collection), [`plugins/dsh-telegram/lib/telegram/api.js`](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/telegram/api.js) (Telegram API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Telegram entry"]
  node_telegram["Telegram API<br/>[api.js]"]
  node_poller["Update polling<br/>[poller.js]"]
  node_router["Update router<br/>[router.js]"]
  node_access["Access control<br/>[access.js]"]
  node_commands["Commands<br/>[commands.js]"]
  node_plugin["Plugin setup<br/>[index.js]"]
end

subgraph group_sessions["Agent sessions"]
  node_session["Session runner<br/>[runner.js]"]
  node_bindings["Session bindings<br/>[bindings.js]"]
  node_history["Session history<br/>[history.js]"]
  node_model["Model selection<br/>[model-selection.js]"]
end

subgraph group_interaction["Chat interaction"]
  node_questions["Agent questions<br/>[questions.js]"]
  node_approvals["Approvals<br/>[approvals.js]"]
  node_surface["Chat surface<br/>[surface.js]"]
  node_capture["Text capture<br/>[text-capture.js]"]
end

subgraph group_media["Media intake"]
  node_media["Media collection<br/>[collect.js]"]
  node_intake["Media intake<br/>[intake.js]"]
  node_ocr["Image OCR<br/>[ocr.js]"]
  node_voice["Voice transcription<br/>[voice.js]"]
end

subgraph group_delivery["Reply delivery"]
  node_turn["Turn bridge<br/>[turn-bridge.js]"]
  node_stream["Rich reply stream<br/>[rich-stream.js]"]
  node_render["Message rendering<br/>[clamp.js]"]
end

node_user(("Telegram user"))
node_harness["DSH Harness"]

node_user -.->|"sends updates"| node_telegram
node_telegram -.->|"provides updates"| node_poller
node_poller -.->|"dispatches updates"| node_router
node_router -.->|"checks access"| node_access
node_router -->|"parses commands"| node_commands
node_router -.->|"prompts agent"| node_session
node_router -.->|"collects media"| node_media
node_router -.->|"handles voice"| node_voice
node_plugin -.->|"starts polling"| node_poller
node_plugin -->|"configures routing"| node_router
node_session -.->|"reads bindings"| node_bindings
node_session -->|"records turns"| node_history
node_session -.->|"delivers prompts"| node_harness
node_model -->|"routes requests"| node_harness
node_questions -.->|"renders prompts"| node_surface
node_approvals -.->|"presents approvals"| node_surface
node_capture -.->|"captures replies"| node_router
node_media -->|"checks image type"| node_intake
node_media -.->|"supplies prompt content"| node_harness
node_ocr -.->|"extracts image text"| node_harness
node_voice -.->|"transcribes audio"| node_harness
node_harness -.->|"emits turn events"| node_turn
node_turn -->|"forwards reply deltas"| node_stream
node_stream -.->|"sends rich drafts"| node_telegram
node_render -.->|"bounds prompts"| node_stream

click node_telegram "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/telegram/api.js"
click node_poller "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/telegram/poller.js"
click node_router "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/router.js"
click node_access "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/access.js"
click node_commands "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/commands.js"
click node_plugin "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/index.js"
click node_session "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/session/runner.js"
click node_bindings "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/session/bindings.js"
click node_history "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/session/history.js"
click node_model "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/harness/model-selection.js"
click node_questions "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/interact/questions.js"
click node_approvals "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/interact/approvals.js"
click node_surface "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/interact/surface.js"
click node_capture "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/interact/text-capture.js"
click node_media "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/media/collect.js"
click node_intake "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/media/intake.js"
click node_ocr "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/media/ocr.js"
click node_voice "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/media/voice.js"
click node_turn "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/reply/turn-bridge.js"
click node_stream "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/reply/rich-stream.js"
click node_render "https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/render/clamp.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_telegram,node_poller,node_router,node_access,node_commands,node_plugin,node_user toneBlue
class node_session,node_bindings,node_history,node_model toneAmber
class node_questions,node_approvals,node_surface,node_capture toneMint
class node_media,node_intake,node_ocr,node_voice toneRose
class node_turn,node_stream,node_render,node_harness toneIndigo
```

## Components

### Telegram entry

- [Telegram API](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/telegram/api.js): `plugins/dsh-telegram/lib/telegram/api.js`
- [Update polling](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/telegram/poller.js): `plugins/dsh-telegram/lib/telegram/poller.js`
- [Update router](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/router.js): `plugins/dsh-telegram/lib/router.js`
- [Access control](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/access.js): `plugins/dsh-telegram/lib/access.js`
- [Commands](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/commands.js): `plugins/dsh-telegram/lib/commands.js`
- [Plugin setup](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/index.js): `plugins/dsh-telegram/lib/index.js`

### Agent sessions

- [Session runner](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/session/runner.js): `plugins/dsh-telegram/lib/session/runner.js`
- [Session bindings](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/session/bindings.js): `plugins/dsh-telegram/lib/session/bindings.js`
- [Session history](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/session/history.js): `plugins/dsh-telegram/lib/session/history.js`
- [Model selection](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/harness/model-selection.js): `plugins/dsh-telegram/lib/harness/model-selection.js`

### Chat interaction

- [Agent questions](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/interact/questions.js): `plugins/dsh-telegram/lib/interact/questions.js`
- [Approvals](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/interact/approvals.js): `plugins/dsh-telegram/lib/interact/approvals.js`
- [Chat surface](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/interact/surface.js): `plugins/dsh-telegram/lib/interact/surface.js`
- [Text capture](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/interact/text-capture.js): `plugins/dsh-telegram/lib/interact/text-capture.js`

### Media intake

- [Media collection](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/media/collect.js): `plugins/dsh-telegram/lib/media/collect.js`
- [Media intake](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/media/intake.js): `plugins/dsh-telegram/lib/media/intake.js`
- [Image OCR](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/media/ocr.js): `plugins/dsh-telegram/lib/media/ocr.js`
- [Voice transcription](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/media/voice.js): `plugins/dsh-telegram/lib/media/voice.js`

### Reply delivery

- [Turn bridge](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/reply/turn-bridge.js): `plugins/dsh-telegram/lib/reply/turn-bridge.js`
- [Rich reply stream](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/reply/rich-stream.js): `plugins/dsh-telegram/lib/reply/rich-stream.js`
- [Message rendering](https://github.com/palomo1632-prog/agente-dsh/blob/main/plugins/dsh-telegram/lib/render/clamp.js): `plugins/dsh-telegram/lib/render/clamp.js`

### Other components

- **Telegram user**
- **DSH Harness**

## Connections

- Telegram user → Telegram API: sends updates (evidence: `README.md`)
- Telegram API → Update polling: provides updates
- Update polling → Update router: dispatches updates
- Update router → Access control: checks access (evidence: `plugins/dsh-telegram/lib/router.js`)
- Update router → Commands: parses commands (evidence: `plugins/dsh-telegram/lib/router.js`)
- Update router → Session runner: prompts agent
- Update router → Media collection: collects media
- Update router → Voice transcription: handles voice
- Plugin setup → Update polling: starts polling (evidence: `plugins/dsh-telegram/lib/index.js`)
- Plugin setup → Update router: configures routing (evidence: `plugins/dsh-telegram/lib/index.js`)
- Session runner → Session bindings: reads bindings (evidence: `plugins/dsh-telegram/lib/session/runner.js`)
- Session runner → Session history: records turns (evidence: `plugins/dsh-telegram/lib/session/runner.js`)
- Session runner → DSH Harness: delivers prompts (evidence: `plugins/dsh-telegram/lib/session/runner.js`)
- Model selection → DSH Harness: routes requests (evidence: `plugins/dsh-telegram/lib/harness/model-selection.js`)
- Agent questions → Chat surface: renders prompts (evidence: `plugins/dsh-telegram/lib/interact/questions.js`)
- Approvals → Chat surface: presents approvals (evidence: `plugins/dsh-telegram/lib/interact/approvals.js`)
- Text capture → Update router: captures replies
- Media collection → Media intake: checks image type (evidence: `plugins/dsh-telegram/lib/media/collect.js`)
- Media collection → DSH Harness: supplies prompt content (evidence: `plugins/dsh-telegram/lib/media/collect.js`)
- Image OCR → DSH Harness: extracts image text (evidence: `plugins/dsh-telegram/lib/media/ocr.js`)
- Voice transcription → DSH Harness: transcribes audio (evidence: `README.md`)
- DSH Harness → Turn bridge: emits turn events (evidence: `plugins/dsh-telegram/lib/reply/turn-bridge.js`)
- Turn bridge → Rich reply stream: forwards reply deltas (evidence: `plugins/dsh-telegram/lib/reply/turn-bridge.js`)
- Rich reply stream → Telegram API: sends rich drafts (evidence: `plugins/dsh-telegram/lib/reply/rich-stream.js`)
- Message rendering → Rich reply stream: bounds prompts (evidence: `plugins/dsh-telegram/lib/render/clamp.js`)
