diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a115a1..025a58b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ You can contribute in many ways: ## Report Bugs -Report bugs at https://github.com/psiace/bub/issues +Report bugs at https://github.com/bubbuild/bub/issues If you are reporting a bug, please include: @@ -33,7 +33,7 @@ bub could always use more documentation, whether as part of the official docs, i ## Submit Feedback -The best way to send feedback is to file an issue at https://github.com/psiace/bub/issues. +The best way to send feedback is to file an issue at https://github.com/bubbuild/bub/issues. If you are proposing a new feature: diff --git a/README.md b/README.md index 608176c..f88c5a0 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,32 @@ # Bub -[![Release](https://img.shields.io/github/v/release/psiace/bub)](https://github.com/psiace/bub/releases) -[![Build status](https://img.shields.io/github/actions/workflow/status/psiace/bub/main.yml?branch=main)](https://github.com/psiace/bub/actions/workflows/main.yml?query=branch%3Amain) -[![Commit activity](https://img.shields.io/github/commit-activity/m/psiace/bub)](https://github.com/psiace/bub/graphs/commit-activity) -[![License](https://img.shields.io/github/license/psiace/bub)](LICENSE) +[![Release](https://img.shields.io/github/v/release/bubbuild/bub)](https://github.com/bubbuild/bub/releases) +[![Build status](https://img.shields.io/github/actions/workflow/status/bubbuild/bub/main.yml?branch=main)](https://github.com/bubbuild/bub/actions/workflows/main.yml?query=branch%3Amain) +[![Commit activity](https://img.shields.io/github/commit-activity/m/bubbuild/bub)](https://github.com/bubbuild/bub/graphs/commit-activity) +[![License](https://img.shields.io/github/license/bubbuild/bub)](LICENSE) > Bub it. Build it. -Bub is a coding agent CLI built on `republic`. -It is designed for real engineering workflows where execution must be predictable, inspectable, and recoverable. +Bub is a collaborative agent for shared delivery workflows, evolving into a framework that helps other agents operate with the same collaboration model. +It is not a personal-assistant shell: it is designed for shared environments where work must be inspectable, handoff-friendly, and operationally reliable. -## Four Things To Know +> Documentation: -1. Command boundary is strict: only lines starting with `,` are treated as commands. -2. The same routing model is applied to both user input and assistant output. -3. Successful commands return directly; failed commands fall back to the model with structured context. -4. Session context is append-only tape with explicit `anchor/handoff` transitions. +Built on [Republic](https://github.com/bubbuild/republic), Bub treats context as explicit assembly from verifiable interaction history, rather than opaque inherited state. +This aligns with [Socialized Evaluation](https://psiace.me/posts/im-and-socialized-evaluation/): systems are judged by how well teams can inspect, review, and continue work together. + +## What Bub Provides + +- Multi-operator collaboration in shared delivery environments. +- Explicit command boundaries for predictable execution. +- Verifiable history (`tape`, `anchor`, `handoff`) for audit and continuity. +- Channel-neutral behavior across CLI and message channels. +- Extensible tools and skills with a unified operator-facing workflow. ## Quick Start ```bash -git clone https://github.com/psiace/bub.git +git clone https://github.com/bubbuild/bub.git cd bub uv sync cp env.example .env @@ -39,7 +45,7 @@ Start interactive CLI: uv run bub ``` -## Interaction Rules +## Interaction Model - `hello`: natural language routed to model. - `,help`: internal command. @@ -62,7 +68,9 @@ Common commands: ,quit ``` -## Telegram (Optional) +## Channel Runtime (Optional) + +Telegram: ```bash BUB_TELEGRAM_ENABLED=true @@ -71,7 +79,7 @@ BUB_TELEGRAM_ALLOW_FROM='["123456789","your_username"]' uv run bub message ``` -## Discord (Optional) +Discord: ```bash BUB_DISCORD_ENABLED=true @@ -81,16 +89,6 @@ BUB_DISCORD_ALLOW_CHANNELS='["123456789012345678"]' uv run bub message ``` -## Documentation - -- `docs/index.md`: getting started and usage overview -- `docs/deployment.md`: local + Docker deployment playbook -- `docs/features.md`: key capabilities and why they matter -- `docs/cli.md`: interactive CLI workflow and troubleshooting -- `docs/architecture.md`: agent loop, tape, anchor, and tool/skill design -- `docs/telegram.md`: Telegram integration and operations -- `docs/discord.md`: Discord integration and operations - ## Development ```bash diff --git a/docs/architecture.md b/docs/architecture.md index dd9cc86..1fecdab 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -8,6 +8,7 @@ This page is for developers and advanced users who need to understand why Bub be 2. Same routing rules for user input and assistant output. 3. Command execution and model reasoning are explicit layers. 4. Phase transitions are represented by `anchor/handoff`, not hidden state jumps. +5. Human and agent operators follow the same collaboration boundaries. ## Runtime Topology diff --git a/docs/channels.md b/docs/channels.md new file mode 100644 index 0000000..b7ab1e1 --- /dev/null +++ b/docs/channels.md @@ -0,0 +1,26 @@ +# Channels + +Bub supports running the same agent loop through message channels. +Use channels when you want remote operation from mobile or shared team environments. + +## Supported Channels + +- [Telegram](telegram.md): direct messages and group chats. +- [Discord](discord.md): servers, channels, and threads. + +## Run Entry + +Start channel mode with: + +```bash +uv run bub message +``` + +If the process exits immediately, check that at least one channel is enabled in `.env`. + +## Session Isolation + +- Telegram session key: `telegram:` +- Discord session key: `discord:` + +This keeps message history isolated per conversation endpoint. diff --git a/docs/cli.md b/docs/cli.md index 293097d..e4f0abc 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,6 +1,6 @@ # Interactive CLI -## Runtime Commands +## Run Commands ```bash uv run bub chat @@ -16,7 +16,7 @@ uv run bub chat \ --session-id cli-main ``` -Other runtime modes: +Other run modes: - `uv run bub run "summarize current repo status"`: one-shot message and exit. - `uv run bub message`: run enabled message channels (Telegram/Discord). diff --git a/docs/deployment.md b/docs/deployment.md index af245ae..cfc79bc 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -11,7 +11,7 @@ This page covers production-oriented setups for Bub, including local process man Quick bootstrap: ```bash -git clone https://github.com/psiace/bub.git +git clone https://github.com/bubbuild/bub.git cd bub uv sync cp env.example .env @@ -32,7 +32,7 @@ Choose one mode based on your operation target: `uv run bub chat` 2. Channel service (Telegram/Discord): `uv run bub message` -3. Scheduler-only autonomous runtime: +3. Scheduler-only autonomous mode: `uv run bub idle` One-shot operation: @@ -115,4 +115,4 @@ uv run mypy uv run pytest -q ``` -Then restart your runtime (`chat`, `message`, or container service). +Then restart your service mode (`chat`, `message`, or container service). diff --git a/docs/discord.md b/docs/discord.md index 9fe66e0..5138b8e 100644 --- a/docs/discord.md +++ b/docs/discord.md @@ -1,6 +1,6 @@ # Discord Integration -Discord allows Bub to run as a remote coding assistant for team channels, threads, and DMs. +Discord allows Bub to run as a remote collaboration endpoint for team channels, threads, and DMs. ## Configure @@ -30,9 +30,9 @@ Notes: uv run bub message ``` -## Runtime Behavior +## Run Behavior -- Uses `discord.py` bot runtime. +- Uses `discord.py` bot service loop. - Each Discord channel maps to `discord:` session key. - Inbound text enters the same `AgentLoop` used by CLI. - Outbound immediate output is sent back in-channel (split into chunks when too long). @@ -49,4 +49,4 @@ uv run bub message 1. Keep bot token only in `.env` or a secret manager. 2. Restrict `BUB_DISCORD_ALLOW_CHANNELS` and `BUB_DISCORD_ALLOW_FROM`. 3. Confirm the bot has message-content intent enabled in Discord Developer Portal. -4. If no response is observed, verify token, allowlists, intents, and runtime logs. +4. If no response is observed, verify token, allowlists, intents, and service logs. diff --git a/docs/features.md b/docs/features.md index 1164098..4d5781d 100644 --- a/docs/features.md +++ b/docs/features.md @@ -1,6 +1,6 @@ # Key Features -This page summarizes the capabilities users rely on most when working with Bub. +This page summarizes the capabilities operators rely on most when working with Bub. ## 1. Deterministic Command Routing @@ -17,9 +17,9 @@ Why it matters: fewer accidental tool calls and more predictable behavior. Why it matters: the assistant can debug based on real command output instead of generic guesses. -## 3. Tape-First Session Memory +## 3. Verifiable Session History and Context Assembly -- Bub writes session activity to append-only tape. +- Bub records session activity as append-only, verifiable history. - `,anchors` and `,handoff` mark phase transitions. - `,tape.search` and `,tape.info` help inspect context quickly. @@ -39,7 +39,7 @@ Why it matters: prompt stays focused while advanced capabilities remain availabl - Rich interactive shell with history and completions. - `Ctrl-X` toggles shell mode for faster command execution. -- Same runtime behavior as channel integrations. +- Same behavior model as channel integrations. Why it matters: local debugging and implementation loops are fast and consistent. diff --git a/docs/index.md b/docs/index.md index d10165f..19333f2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,45 +1,39 @@ # Bub Docs -Bub is built for day-to-day coding tasks: run commands, edit files, debug failures, and keep progress visible across long sessions. +Bub is a collaborative agent for shared delivery workflows, evolving into a framework that helps other agents operate with the same collaboration model. +If you only remember one thing from this page, remember this: Bub is built for shared delivery workflows where execution must be inspectable, handoff-friendly, and repeatable. -## What You Can Expect +Under the hood, Bub uses [Republic](https://github.com/bubbuild/republic) to assemble context from traceable history instead of inheriting opaque state. +Its operating philosophy follows [Socialized Evaluation](https://psiace.me/posts/im-and-socialized-evaluation/): quality is judged by whether teams can inspect decisions and continue work safely. -- Clear command behavior: only lines that start with `,` are commands. -- One execution path: the same rules apply to both your input and assistant-generated commands. -- Graceful recovery: failed commands are fed back to the model with structured context. -- Trackable sessions: tape, anchors, and handoff help you resume work cleanly. +## What Bub Is (and Is Not) -## How Bub Behaves In Practice +- Bub is a collaboration agent for human and agent operators. +- Bub is not a personal-assistant-only chat shell. +- Bub keeps command execution explicit, reviewable, and recoverable. -1. Type normal text to ask the assistant. -2. Start a line with `,` to run a command. -3. Known names such as `,help` are internal commands. -4. Other comma-prefixed lines are treated as shell commands. -5. If a command fails, Bub keeps going and uses the error context in the next model step. +## How Bub Works -## Start Here +1. Input boundary: only lines starting with `,` are treated as commands. +2. Unified routing: the same routing rules apply to user input and assistant output. +3. Structured fallback: failed commands are returned to the model with execution evidence. +4. Persistent evidence: interaction history is append-only (`tape`) and can be searched. +5. Explicit transitions: `anchor` and `handoff` represent phase changes and responsibility transfer. -- [Key Features](features.md) -- [Interactive CLI](cli.md) -- [Deployment Guide](deployment.md) -- [Architecture](architecture.md) -- [Telegram Integration](telegram.md) -- [Discord Integration](discord.md) +## Checklist -## Common Commands +1. Start with model + API key in `.env`. +2. Run `uv run bub` and ask a normal question. +3. Run `,help` and `,tools` to inspect available capabilities. +4. Execute one shell command like `,git status`. +5. Create one handoff: `,handoff name=phase-1 summary="..."`. +6. Verify history using `,tape.info` or `,tape.search query=...`. -```text -,help -,tools -,tool.describe name=fs.read -,tape.info -,tape.search query=timeout -,handoff name=phase-2 summary="router fixed" next_steps="run pytest" -,anchors -,tape.reset archive=true -``` +## Where To Read Next -## Configuration - -Start from `env.example` in the repository root. -Use model + API key first, then add Telegram and advanced settings when needed. +- [Key Features](features.md): capability-level overview. +- [Interactive CLI](cli.md): interactive workflow and troubleshooting. +- [Architecture](architecture.md): runtime boundaries and internals. +- [Deployment Guide](deployment.md): local and Docker operations. +- [Channels](channels.md): Telegram and Discord runtime model. +- [Post: Socialized Evaluation and Agent Partnership](posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership.md): project position and principles. diff --git a/docs/posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership.md b/docs/posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership.md new file mode 100644 index 0000000..7c3f500 --- /dev/null +++ b/docs/posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership.md @@ -0,0 +1,68 @@ +--- +title: "Bub: Socialized Evaluation and Agent Partnership" +date: 2026-03-01 +description: "Why Bub is designed as an agent partner system where humans and agents share the same operator model." +--- + +# Bub: Socialized Evaluation and Agent Partnership + +I care less about whether an agent can complete a demo task, and more about whether a real team can trust it under pressure. +That is where most systems fail: not at capability, but at collaboration. + +Bub is not designed as a personal-only assistant. +It is designed for shared environments where humans and agents are treated as equivalent operators. +Current deployments may use one primary agent, but the collaboration model itself is symmetric: the same boundaries, evidence model, and handoff semantics apply to both humans and agents. + +The practical goal is simple: when work gets messy, Bub should still feel like a dependable teammate. +It should make execution visible, handoff safe, and continuation predictable. + +## From Tool Execution to Human Partnership + +Many agent systems focus on whether a model can execute commands. +For real teams, that is not enough. +What matters is whether outcomes remain understandable, reviewable, and improvable over long time horizons. + +Bub treats this as a first-class design target: + +- Agents should assist human workflows, not replace human judgment. +- Operator decisions, agent actions, and execution evidence should stay visible. +- Collaboration should remain stable when more operators and automation layers join. + +## Socialized Evaluation as a System Principle + +In Bub, evaluation is not only model-centric. +It is social by design: + +- Can teammates inspect what happened and why? +- Can reviewers audit decisions without hidden state? +- Can future operators continue work from recorded evidence? +- Can all operators (human or agent) coordinate without opaque side effects? + +If the answer is no, the system is not reliable enough for production collaboration. +The term "Socialized Evaluation" follows the framing in [Instant Messaging and Socialized Evaluation](https://psiace.me/posts/im-and-socialized-evaluation/). + +## Why Operator Equivalence by Default + +Single-user flows can hide many structural problems. +Multi-operator settings expose them quickly: state conflicts, unclear responsibility, and fragile context boundaries. + +Bub is built with these constraints from day one: + +- Explicit command boundaries. +- Verifiable execution history with explicit anchor and handoff points. +- Handoff and anchors for continuity across people and phases. +- Channel/runtime neutrality for different operation surfaces. + +This is how Bub moves from "assistant behavior" to "collaboration infrastructure." + +## Relationship to Republic + +Bub uses [Republic](https://github.com/bubbuild/republic) as its context runtime. +Republic's key value is not "a better memory trick." It reframes the problem: keep interaction history as verifiable facts, then assemble minimally sufficient context for each task. +Bub builds on that model to support practical collaboration workflows where humans and agents participate as equivalent operators. + +## Closing + +Our direction is simple: + +Build agents that are useful in real social systems, not only impressive in isolated demos. diff --git a/docs/telegram.md b/docs/telegram.md index d5cc46a..0437553 100644 --- a/docs/telegram.md +++ b/docs/telegram.md @@ -1,6 +1,6 @@ # Telegram Integration -Telegram allows Bub to run as a remote coding assistant entry point for lightweight operations. +Telegram allows Bub to run as a remote collaboration entry point for lightweight operations. ## Configure @@ -24,7 +24,7 @@ Notes: uv run bub message ``` -## Runtime Behavior +## Run Behavior - Uses long polling. - Each Telegram chat maps to `telegram:` session key. @@ -38,5 +38,5 @@ uv run bub message 1. Keep bot token only in `.env` or a secret manager. 2. Use a dedicated bot account. 3. Keep allowlist updated with valid user IDs/usernames. -4. If no response is observed, check network, token, allowlists, then runtime/model logs. +4. If no response is observed, check network, token, allowlists, then service/model logs. 5. If `uv run bub message` exits quickly, verify at least one channel is enabled (`BUB_TELEGRAM_ENABLED=true`). diff --git a/mkdocs.yml b/mkdocs.yml index 391c805..6886829 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,20 +1,25 @@ site_name: bub -repo_url: https://github.com/psiace/bub +repo_url: https://github.com/bubbuild/bub site_url: https://bub.build -site_description: Bub it. Build it. -site_author: Chojan Shang +site_description: "An agent partner for real teams: visible execution, reliable collaboration." +site_author: Bub Build edit_uri: edit/main/docs/ -repo_name: psiace/bub -copyright: Maintained by Chojan Shang. +repo_name: bubbuild/bub +copyright: Copyright (c) 2026 Bub Build contributors. nav: - Home: index.md - Key Features: features.md + - Posts: + - "2026-03-01 · Socialized Evaluation and Agent Partnership": posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership.md + - "2025-07-16 · Baby Bub Bootstrap Milestone": posts/2025-07-16-baby-bub-bootstrap-milestone.md - Deployment: deployment.md - Architecture: architecture.md - Interactive CLI: cli.md - - Telegram: telegram.md - - Discord: discord.md + - Channels: + - Overview: channels.md + - Telegram: telegram.md + - Discord: discord.md plugins: - search @@ -58,6 +63,6 @@ markdown_extensions: extra: social: - icon: fontawesome/brands/github - link: https://github.com/psiace/bub + link: https://github.com/bubbuild/bub - icon: fontawesome/brands/python link: https://pypi.org/project/bub diff --git a/pyproject.toml b/pyproject.toml index e0b2f23..dead7dd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,8 +1,12 @@ [project] name = "bub" version = "0.2.3" -description = "Bub it. Build it. Tape-first coding agent CLI." -authors = [{ name = "Chojan Shang", email = "psiace@apache.org" }] +description = "Bub it. Build it. A collaborative agent for shared delivery workflows." +authors = [ + { name = "Chojan Shang", email = "psiace@apache.org" }, + { name = "Frost Ming", email = "me@frostming.com" }, + { name = "Hong Yi", email = "zouzou0208@gmail.com" }, +] readme = "README.md" keywords = ['python'] requires-python = ">=3.12,<4.0" @@ -39,7 +43,7 @@ dependencies = [ [project.urls] Homepage = "https://bub.build" -Repository = "https://github.com/psiace/bub" +Repository = "https://github.com/bubbuild/bub" Documentation = "https://bub.build" [project.scripts]