convos-runtime (0.1.0)
Installation
pip install --index-url About this package
Local-first participation layer for bringing existing AI agents into existing chat
Convos Runtime
Convos is a lightweight, local-first runtime that connects existing AI agents to familiar messaging surfaces while keeping their workspaces, credentials, and operational control in their existing environments.
Reading order:
docs/00-vision.md
-> vision, positioning, product thesis
docs/02-terminology.md
-> canonical product, messaging, agent, runtime, identity, and authority terminology
docs/05-background-context.md
-> optional background from early concept shaping
docs/10-runtime-design.md
-> runtime design, channel abstraction, session mapping, lifecycle, prompt contracts
docs/15-conversation-scenarios.md
-> concrete conversation scenarios, reception matching, multi-chat topic sessions
docs/20-first-build-architecture.md
-> concrete first-build architecture, records, state store, routing flow, implementation order
docs/22-channel-accounts-and-agent-bindings.md
-> internal/external IM accounts, agent bindings, identity, authorization, and onboarding
docs/25-product-shape.md
-> product value, market-relevant capabilities, design implications before implementation
docs/30-implementation-blueprint.md
-> implementation defaults, folder layout, CLI, local channel format, schema, technical phase scope
docs/31-agent-support-and-onboarding-model.md
-> canonical agent-product, connection-family, work-context, lifecycle, compatibility, and onboarding model
docs/32-agent-onboarding-and-local-chat.md
-> implemented local browser chat, current guided onboarding, and command/HTTP adapter contracts
docs/33-roadmap-and-status.md
-> canonical current milestone, roadmap order, exit gates, evidence, and deferred options
docs/35-market-positioning.md
-> dated competitive map, developer-first positioning, validation gates, market decisions
docs/40-market-review-strategy.md
-> recurring and event-triggered review process for a fast-changing AI market
docs/41-post-delivery-review-strategy.md
-> future-review inbox plus post-delivery technical, security, product, and maintenance review process
docs/43-gitea-local-runner-setup.md
-> Windows runner setup for AWS-hosted Gitea and a separate local deployment
docs/44-acp-connectivity-and-session-routing.md
-> current session linkage, intended topic switching, and ACP compatibility investigation
Use the terminology reference as the source of truth when discussing or revising product,
marketing, UI, architecture, and implementation language. Some existing documents and code retain earlier
channel_* names until a coordinated cleanup.
Core idea:
Bring the agents you already use into the conversations you already use.
Convos keeps agent runtimes and IM providers behind independent adapters, preserves session mappings and native
session lifecycle when an adapter supports it, and makes routing, activity, delivery, and failure inspectable.
Single-network and cross-network coordination are uses of this backbone, not separate first-version feature bundles. Stronger identity, authority, and federation mechanisms remain optional extensions driven by real integrations.
Current implementation status and roadmap order live only in the canonical roadmap. Design documents describe scope and acceptance behavior; do not infer current status from their section order.
Before publishing the software, discuss whether Convos should be open source, community-use freeware, or an intermediate model, including how experienced solo development with AI changes the value of outside contributions. The discussion is recorded as RVW-002. The publishing model and license remain undecided.
The target architecture puts the internal browser chat and external IM integrations behind one account model. Each configured adapter instance becomes a ChannelAccount; agents become eligible through explicit AgentChannelBinding records, then acquire per-room SessionMapping records only after actual involvement. The current local runtime still uses compatible channel_id records while this migration is pending. See the channel-account design.
Run the local chat
Create an isolated environment and run the complete suite from this convos_software directory. On Windows:
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m unittest discover -s tests
On macOS or Linux, use .venv/bin/python in the same commands. The current verified platform evidence is Windows;
cross-platform verification remains a later roadmap gate.
The default setup opens a local browser workspace with persisted group rooms, one-to-one agent chats, and the
deterministic Echo Agent at @echo. Its reply to a human starts with You said: ... on one line, followed by a
rotating next-step hint and compact routing trace on consecutive lines. The setup also seeds one local human
administrator and a dormant Convos Admin agent;
the Admin uses the normal agent model but shows Needs runtime until a supported runtime is configured. Compatible
older local installations gain the same missing Admin presence when their configuration loads, without replacing
their existing agents:
python -m pip install -e .
convos init
convos serve
Open http://127.0.0.1:4317. In a normal room, send @echo hello from this room. To talk to one configured agent
without mentioning it on every message, choose that agent under Direct messages in the Rooms column or run:
convos chat-direct --agent demo-helper
Opening a direct chat is idempotent: the same local room is returned for that channel and agent. Plain messages in that room route only to its selected agent, and mentioning another agent does not add it to the conversation.
Convos reserves two loopback-only ports with distinct ownership:
4317is the live runtime controlled by the human operator. Plainconvos servealways uses this port.4318is the ai-work runtime used by AI-assisted development and temporary manual verification.
The role selects a managed port, not stored state. Use the global --instance-dir option on every AI-work command so
manual verification cannot share the live configuration, database, channel log, or sessions. For this checkout,
.ai-folder/ai-working is the ignored location reserved for temporary AI work:
convos --instance-dir ../.ai-folder/ai-working/convos-ai-work init
convos --instance-dir ../.ai-folder/ai-working/convos-ai-work serve --role ai-work
This stores mutable files under ../.ai-folder/ai-working/convos-ai-work/.convos/. --instance-dir and --config
are mutually exclusive. The option selects Convos instance state only; relative agent repository paths and static
sample discovery remain anchored to the directory where the command was launched. Automated tests continue to use
operating-system temporary directories and ephemeral ports rather than this persistent manual-testing instance.
On startup, convos serve prints the package version, source build fingerprint, and resolved instance directory.
convos status checks both ports, prints the local CLI build, and asks each running listener for its version, build,
and instance directory alongside the listener PID. This makes a stale or incorrectly targeted server visible. Use
convos status --json for structured output.
Before starting either managed role, serve checks its dedicated port. If a process already owns that port, Convos identifies it, warns that it will be replaced, and waits five seconds. Press Ctrl+C during that window to keep the existing process. Otherwise Convos terminates the same verified PID, confirms that the port is free, and continues startup; failure to release the port stops startup with an error.
The browser opens on the Workspace view. Its first three columns show Agents, Sessions, and
Rooms; the fourth is the active Conversation. On the four-column layout, their captions stay visible in a
page-specific subheader while the workspace map scrolls. Selecting a room updates the thread in place and
highlights its real route back through associated sessions and agents. Direct messages and multi-agent rooms share
the Rooms column, and choosing a ready agent there creates its direct chat on first use. Use the Rooms-column add
control or
convos chat-create --chat release-planning --name "Release planning" to create a group room.
The Agent column ends with Add agent for guided Codex repository onboarding. The compact header keeps Workspace and Admin on its first line and shows the active destination's description below. Admin separates Access requests from Runtime tools; Runtime tools switches between Recovery, History, and paged State. Dormant agents stay visible but cannot be messaged until their runtime setup is complete. Convos Admin's contextual setup action reports that runtime/model configuration is not available yet instead of presenting a false configuration flow.
Admin > Prompts shows the loaded Convos participation, collaboration/peer-review, room-audience, and Codex
invocation text, with its source file, version, and fingerprint. The authoritative prose is in
src/convos_runtime/prompts, loaded at startup. Edit those source files, rebuild or
reinstall if needed, and restart the instance to apply changes. The view is read only; native provider and workspace
instructions remain separate. See prompt organization.
When a convos_sample_workspace directory is present beside this package or at the project/config base, Add agent shows
See examples below the Repository path input. The link opens a lightly tinted inset section with a left border
containing the example agent setups; Hide examples closes it. Required fields carry an asterisk; name, mention,
and ID are optional. Choosing a workspace fills the repository, display
name, mention, and agent ID fields, while the group shows which related workspaces remain. An empty room offers each
prepared opening message when its required agents are ready; unrelated agents in the setup need not be connected.
Group stories appear in group rooms, while owner-only starters appear only in the matching agent's direct chat.
Choosing a starter fills the composer for review and sending; it does not send or change rooms.
The example catalog contains five setups for one person on one computer: Client projects, Personal assistance, Home lab, Local and cloud agents, and Model resource tiers. Their fourteen workspace folders and twelve opening stories separate client context, private/public information, live/test evidence, independently configured runtimes and tools, or local/free/premium resource budgets. Start with Client projects. Each setup README describes the evidence gap, why the agents are separate, and the follow-up messages the human can carry between them. Agent replies are not automatically redispatched, and these examples add no scheduler, provider integration, ACP adapter, enforced quota, or confidentiality boundary. Model resource tiers demonstrates checkpoint handoffs, stronger-model direction and work allocation, independent peer checks, and cover when a lead's allowance ends. The owner carries approved follow-up messages. The older software-distribution, residential-delivery, and escrow folders remain intact for existing connections, including Maya, but are hidden from See examples.
The catalog is read in place and receives no Convos runtime files, copies, or Git initialization.
Onboarding defaults to read-only; choosing Allow edits explicitly permits changes to the source template and makes
them visible in the surrounding Git worktree. Codex treats the selected folder as its project-instruction root, so an
agent for one sample workspace does not inherit AGENTS.md, project configuration, or repository skills from parent
or sibling folders. This instruction boundary does not restrict what the host account can read.
The local-first design notes record the story-driven boundaries and the distinction between the implemented demonstrations and possible future automation.
Each chat header has room options matching normal IM lifecycle controls. Clear history hides the room's existing
transcript but keeps the room and its linked agents. Delete room removes a non-default group room and detaches its
mappings; deleted room IDs cannot be reused. Direct chats and the default general room can be cleared but not
deleted. Both operations retain append-only channel and SQLite audit records, discard undelivered replies from the old
history, and refuse to run while dispatch is queued, retrying, or running, or while a reply is actively being published
in that room. CLI equivalents are:
convos chat-clear --chat release-planning
convos chat-delete --chat release-planning
These direct chats belong only to the single-operator local browser surface. They do not implement external-provider DMs, participant authentication, or a privacy boundary.
Sending a browser message returns 202 Accepted only after the inbound fact, ordered dispatch job, and channel cursor
are durable in SQLite. Local workers claim jobs with leases and generation fencing, recover expired work, enforce each
agent's configured concurrency, and suppress late output from a stale or cancelled worker. Invocation and outbound
delivery use separate bounded retry/dead-letter state so a publication fault does not rerun the agent. Browser
delivery and active-work labels rebuild from durable state after reconnect. Adapter/process activity remains a
separate collapsed Run details disclosure, including real Codex command events. Completed details sit below their
own reply; active or failed work sits below the triggering message. The disclosure identifies the working session,
and a recorded routing step identifies its separate Reception session. Reception currently uses a deterministic
session chooser, not another model call. The most recent 20 completed runs with technical details remain available
per room, with up to 12 technical entries per run. These events are stored separately in SQLite's runtime audit, not
in the conversation transcript. Clear history hides their projection without erasing the audit. Polling preserves
selected text, and completed disclosures can be reopened.
State, room, and admin polling are read-only. Startup initializes the SQLite schema and configuration once per owning
runtime; background workers reuse attached connections and refresh their configuration between jobs when it changes.
Lease heartbeats attach without repeating initialization. SQLite retains WAL mode and its five-second write wait;
a busy/locked database during a GET returns JSON 503 with Retry-After: 1 instead of dropping the request. This does
not retry message submissions or imply that live and AI-work ports should share instance state.
The header's Convos service indicator reports the browser's connection to the Convos server on this computer. Individual agents have their own readiness indicators.
Page-level fetch and action failures appear in one translucent floating notice without moving the workspace. The notice remains for 12 seconds, shows its remaining time, and pauses while hovered or focused. Moving the pointer away resumes the countdown once focus is outside, and the close button dismisses it immediately. Repeated identical errors do not replace selected text or restart the timer. A dismissed error can appear again after the failing operation recovers and fails anew. Dialog validation stays inline until the user corrects or dismisses it.
Use convos inspect dispatch, convos inspect dispatch-targets, convos inspect dead-letters, and
convos inspect outbound-dead-letters for diagnosis. convos retry-dead-letters explicitly requeues terminal failed
work. convos cancel-dispatch --dispatch <id> requests cooperative cancellation; command and Codex subprocesses are
terminated when they observe it, while HTTP cancellation suppresses late output after an in-flight request returns.
Each web action shows its reproducible CLI equivalent and structured result. Runtime controls such as run-once and publish-pending are recorded in the event log with their source (cli, web_admin, or web_chat). The CLI and web API call the same operation service; the web server does not launch shell commands for shared operations.
The first real onboarding flow connects the locally authenticated Codex CLI to a Git repository. In Workspace, select Add agent, or run:
convos onboard codex-repo --repo ../my-project --access read-only
Convos verifies the repository, Codex installation, and local Codex login before adding the profile. Read-only access is the default; --access workspace-write explicitly permits repository edits. Convos stores the verified Codex executable path and successful check metadata, not the Codex login token.
A local runtime, CLI, or agent can instead place an inert request into the administrator review inbox:
convos request-onboarding --requester repo-agent --message "Connect this repository" --proposal codex-repo --repo ../my-project
convos onboarding-requests --status pending
convos review-onboarding --request <request-id> --approve
The requester cannot approve itself. Approval applies only the proposal stored with the request and runs the same deterministic checks as direct onboarding. MCP, externally authenticated request intake, and live model-backed Convos Admin operation are not implemented.
When a room mapping is initialized or refreshed, Convos posts its own receipt-based notice separately from the agent's
reply. It explains a recorded change, such as updated Convos participation instructions, and distinguishes a context
refresh from a replacement working session. Echo Agent keeps initialization receipts for audit but emits no AI-session
notice. The Codex repository adapter also asks Codex to load the selected workspace's AGENTS.md guidance and report
the instructions it applied; that report is runtime audit data, not another chat introduction. Parent and sibling
project instructions are excluded.
Codex working sessions now retain the native thread ID and resume that exact thread on later turns. Existing ephemeral sessions cannot be recovered; their next turn starts a persistent native thread using the available conversation history. Later prompt refreshes keep an eligible working/native session and supply the reason to the agent. Native session files remain in Codex-managed storage, separate from Convos instance state and sample folders. Clearing a room's visible history does not erase native memory, which may include other rooms mapped to the same session. See Codex continuity and limits.
All adapters receive shared Convos participation guidance: build an evidence-based understanding of the participants, interpret what the current exchange calls for, and choose a contribution proportionate to its purpose and audience. The guidance supports judgment rather than prescribing responses to particular message types. Workspace instructions supply the agent's own facts and responsibilities. See prompt organization and communication rules for the implemented layers and their limits.
Agent profiles currently support four adapter types:
codex_repo: first-class Codex CLI integration scoped to one selected workspace inside a Git worktreedemo: built-in deterministic agent for trying the full chat loopcommand: a local executable running in its configured repo or workspacehttp: a local HTTP service or HTTPS cloud endpoint
The admin surface is unauthenticated but is now restricted to loopback addresses and rejects non-loopback Host headers. Mutating browser requests must be same-origin JSON, and responses include restrictive browser security headers. External network access still requires a future authenticated admin boundary rather than weakening this local restriction.