Define the transport-neutral Durex control API
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## Parent and milestone
- Parent issue: #23
- Milestone: not scheduled; design follows the local console and audit
contracts in #12-#14.
## Problem
Telegram currently invokes application behavior in process, while the roadmap
promises future web and mobile clients. Without stable query, command,
view-model, idempotency, authentication, and event-stream contracts, a GUI
would either depend on Telegram rendering or query persistence directly.
## Outcome
Define a transport-neutral Durex control API that Telegram can consume in
process and future authenticated HTTP/SSE or WebSocket adapters can expose
without changing task, runtime, interaction, or plugin ownership.
## Scope
- Define versioned task, run, worker, interaction, usage, and pipeline view
models.
- Define query and command services with structured errors and idempotency
keys.
- Define cursor-based live-output and event-stream contracts.
- Define authentication, authorization, redaction, optimistic concurrency, and
audit requirements for a future network adapter.
- Keep Telegram rendering and callback payloads outside the application
contract.
- Define compatibility and schema-generation requirements for web and mobile
clients.
- Keep the base API independent of any specific runtime adapter. Runtime data
uses normalized identifiers and capabilities, with later additions reviewed
against #26.
## Non-goals
- Building the web or mobile GUI in this issue.
- Exposing SQLite, runtime SDKs, plugin processes, or Codex/OpenCode/Pi servers
directly.
- Opening an unauthenticated network listener.
- Waiting for a particular external runtime before defining task, run, worker,
interaction, and output contracts.
## Acceptance criteria
- [ ] Telegram console operations can be expressed entirely through the query
and command contract.
- [ ] DTOs do not contain Telegram payloads, SQLite rows, process ids, or
provider SDK objects.
- [ ] Mutating commands define authorization, idempotency, concurrency, and
audit behavior.
- [ ] Live output and normalized events have bounded cursor/resume semantics.
- [ ] Runtime-facing fields use provider-neutral identifiers and capabilities.
- [ ] A fake client conformance suite covers queries, commands, stale state,
replay, and authorization failure.
- [ ] API, security, compatibility, and future-client documentation is
included.
## Validation
- Review against #12 live console, #13 interaction audit, and #14
configuration contracts.
- Review runtime-facing extensions against #26 before they become public.
- Validate generated schema fixtures and a fake in-process adapter before
adding HTTP.
## Dependencies
- #12, #13, and #14 establish the initial application-service boundary.
- #26 is a coordination contract for later runtime-facing fields, not a blocker
for the base transport-neutral API.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing the live console, interaction audit, and configuration contracts in issues #12, #13, and #14, then check runtime-facing extensions against #26. Define the transport-neutral query and command contracts, view models, event semantics, and security requirements without exposing Telegram or persistence details. Done means the listed acceptance criteria are covered, including schema fixtures and a fake in-process adapter.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, backend-api-design, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100