didericis/bot-bottle
1
0
Fork 0
Code Issues 8 Pull Requests 6 Actions Packages Projects Releases Wiki Activity

Forge native integration: PRD + forge library layer #318

Open
didericis-claude wants to merge 9 commits from forge-native-integration into main
pull from: forge-native-integration
merge into: didericis:main
Conversation 7 Commits 9 Files Changed 17
+1958 -10
didericis-claude commented 2026-06-29 12:10:56 -04:00
Collaborator
Copy Link
Copy Source

Closes #317.

PRD

Design

Forge-native runs are driven by a forge sidecar (option 3): the agent calls the sidecar, which holds the forge token and makes the actual Gitea API calls. The agent never sees the credential or a forge-specific endpoint. Completion is an unambiguous signal_done(status, summary) sidecar call relayed to the orchestrator over a queue dir — no comment-parsing. Scope is read-anywhere / write-scoped: reads for context are unrestricted; writes are limited to the assigned issue and its PRs.

The orchestration loop + webhook listener live in a separate binary (bot-bottle-orchestrator, a PRD non-goal). This PR covers bot-bottle's side of that contract.

What this PR implements

The self-contained forge library layer both the sidecar and orchestrator build on (PRD chunks 1–3, 5):

  • contrib/forge/base.py — Forge ABC + ScopedForge, enforcing read-anywhere / write-scoped (ForgeScopeError on out-of-scope writes).
  • contrib/gitea/client.py — GiteaClient (stdlib-only HTTP, mirrors the deploy-key provisioner) + GiteaForge. Token held by the caller (the sidecar), not injected by cred-proxy.
  • contrib/gitea/forge_state.py — ForgeState + atomic read/write/delete/all under ~/.bot-bottle/forge/<owner>/<repo>/.
  • contrib/gitea/provenance.py — build_provenance_footer, the collapsed markdown audit footer (watchdog / gitleaks / egress rows).
  • cli/resume.py — resume --headless --prompt, reusing the shipped assume_yes + headless_prompt launch core (the new half of chunk 1).

47 new unit tests; pylint 9.98/10, pyright clean.

Deferred (correctly out of scope here)

  • Forge sidecar (chunk 4) and orchestrate command (chunk 6): their only consumer is the separate orchestrator; untestable as standalone shells in this repo.
  • forge_env plumbing: no in-repo consumer until the sidecar exists.

Merge rule(s)

Requires human review and merge — no auto-merge.

Closes #317. [PRD](https://gitea.dideric.is/didericis/bot-bottle/src/branch/forge-native-integration/docs/prds/prd-new-forge-native-integration.md) ## Design Forge-native runs are driven by a **forge sidecar** (option 3): the agent calls the sidecar, which holds the forge token and makes the actual Gitea API calls. The agent never sees the credential or a forge-specific endpoint. Completion is an unambiguous `signal_done(status, summary)` sidecar call relayed to the orchestrator over a queue dir — no comment-parsing. Scope is **read-anywhere / write-scoped**: reads for context are unrestricted; writes are limited to the assigned issue and its PRs. The orchestration loop + webhook listener live in a separate binary (`bot-bottle-orchestrator`, a PRD non-goal). This PR covers **bot-bottle's side of that contract**. ## What this PR implements The self-contained forge library layer both the sidecar and orchestrator build on (PRD chunks 1–3, 5): - **`contrib/forge/base.py`** — `Forge` ABC + `ScopedForge`, enforcing read-anywhere / write-scoped (`ForgeScopeError` on out-of-scope writes). - **`contrib/gitea/client.py`** — `GiteaClient` (stdlib-only HTTP, mirrors the deploy-key provisioner) + `GiteaForge`. Token held by the caller (the sidecar), not injected by cred-proxy. - **`contrib/gitea/forge_state.py`** — `ForgeState` + atomic read/write/delete/all under `~/.bot-bottle/forge/<owner>/<repo>/`. - **`contrib/gitea/provenance.py`** — `build_provenance_footer`, the collapsed markdown audit footer (watchdog / gitleaks / egress rows). - **`cli/resume.py`** — `resume --headless --prompt`, reusing the shipped `assume_yes` + `headless_prompt` launch core (the new half of chunk 1). 47 new unit tests; pylint 9.98/10, pyright clean. ## Deferred (correctly out of scope here) - **Forge sidecar** (chunk 4) and **`orchestrate` command** (chunk 6): their only consumer is the separate orchestrator; untestable as standalone shells in this repo. - **`forge_env` plumbing**: no in-repo consumer until the sidecar exists. ## Merge rule(s) Requires human review and merge — no auto-merge.
didericis-claude added 1 commit 2026-06-29 12:10:59 -04:00
docs: add PRD for forge native integration b607d68a0e
didericis-claude added 1 commit 2026-06-29 12:39:12 -04:00
docs: update forge PRD — orchestrator split, done signal, org targeting, forge env vars 1789deaf73
didericis added 1 commit 2026-06-30 17:39:41 -04:00
docs(prd): adopt forge sidecar (option 3) for native integration ebad90bfa9 
Flip the forge-native-integration PRD from option 2 (agent calls the
Gitea API directly via cred-proxy; done signal parsed from comments) to
option 3 per issue #317 comment 2715: a forge sidecar backed by a Forge
abstract class.

- signal_done(status, summary) replaces comment-parsing as the done signal
- semantic audit trail from the sidecar feeds provenance directly
- read-anywhere / write-scoped enforcement, tighter than repo-wide API keys
- forge-agnostic agent prompts and sidecar protocol
- DeployKeyProvisioner subsumption deferred; share the HTTP client only

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WL77TgFxKbs3cidGMG9dz7
didericis added 1 commit 2026-06-30 17:47:02 -04:00
docs(prd): reconcile headless primitives with shipped start --headless 4cb106b48d 
#315 already merged `start --headless` (assume_yes on _launch_bottle +
AgentProvider.headless_prompt). The PRD's proposed start_headless /
attach_agent_headless helpers were redundant with it, and the latter
diverged by hand-rolling --no-interactive/-p instead of using the
headless_prompt provider abstraction. Drop them.

Scope the remaining headless work to what's actually new: a forge_env
hook threaded into the existing _launch_bottle core, and a `resume
--headless` path (resume has no non-interactive entry point today).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WL77TgFxKbs3cidGMG9dz7
didericis added 2 commits 2026-06-30 19:39:57 -04:00
Merge remote-tracking branch 'origin/main' into forge-native-integration 738990b2df
feat(forge): forge library layer for native integration (PRD chunks 1-3, 5)
lint / lint (push) Failing after 2m9s
Details
test / unit (pull_request) Successful in 58s
Details
test / integration (pull_request) Successful in 21s
Details
test / coverage (pull_request) Successful in 1m23s
Details
a229a22d54 
Implements the bot-bottle side of the forge-native PRD that is
self-contained in this repo (the forge sidecar and orchestrate command
belong to the separate bot-bottle-orchestrator, a PRD non-goal):

- contrib/forge/base.py: Forge ABC + ScopedForge enforcing the
  read-anywhere / write-scoped model (writes rejected outside the
  assigned issue/PRs via ForgeScopeError).
- contrib/gitea/client.py: GiteaClient (stdlib-only HTTP, mirrors the
  deploy-key provisioner) + GiteaForge. Token held by the caller (the
  sidecar), not injected by cred-proxy.
- contrib/gitea/forge_state.py: ForgeState dataclass + atomic
  read/write/delete/all under ~/.bot-bottle/forge/<owner>/<repo>/.
- contrib/gitea/provenance.py: build_provenance_footer — collapsed
  markdown audit footer; watchdog/gitleaks/egress rendering.
- cli/resume.py: `resume --headless --prompt` reusing the shipped
  assume_yes + headless_prompt launch core (the new half of chunk 1).

47 new unit tests; pylint 9.98/10, pyright clean. Forge sidecar (chunk
4), orchestrate command (chunk 6), and forge_env plumbing are deferred:
their only consumer is the separate orchestrator and they are untestable
in isolation here.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WL77TgFxKbs3cidGMG9dz7
didericis-claude changed title from PRD: Forge native integration to Forge native integration: PRD + forge library layer 2026-06-30 22:41:17 -04:00
didericis added 1 commit 2026-07-01 07:59:08 -04:00
fix(tests): resolve pyright strict errors in forge test helpers
lint / lint (push) Successful in 2m18s
Details
test / unit (pull_request) Successful in 1m1s
Details
test / integration (pull_request) Successful in 22s
Details
test / coverage (pull_request) Successful in 1m19s
Details
f211ece6bf 
CI runs `pyright .` over the whole repo including tests; the earlier
run only checked the source paths. The test helpers used `**over`
dict-splat into typed constructors, which pyright strict rejects.

- forge_state: build a typed ForgeState base and dataclasses.replace(**over)
- provenance: explicit typed keyword params instead of a **over dict
- resume: _launch_kwargs returns dict[str, Any] (copy call_args.kwargs)
- forge_base: assert PermissionError in __mro__ (avoids always-true issubclass)
- client: annotate _resp body param; type: ignore the mock __enter__ lambda

pyright . now 0 errors; 47 tests still pass; pylint 9.97/10.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WL77TgFxKbs3cidGMG9dz7
didericis reviewed 2026-07-01 08:02:43 -04:00
bot_bottle/contrib/forge/base.py
@@ -0,0 +27,4 @@
@dataclass(frozen=True)
class Issue:
"""A forge issue or PR (forges model PRs as issues with the same
number)."""
didericis commented 2026-07-01 08:02:43 -04:00
Owner
Copy Link
Copy Source

There should also be a “PullRequest” dataclass/issues and PullRequests should not use the same object

There should also be a “PullRequest” dataclass/issues and PullRequests should not use the same object
didericis reviewed 2026-07-01 08:03:43 -04:00
bot_bottle/contrib/forge/base.py
@@ -0,0 +53,4 @@
@abc.abstractmethod
def read_issue(self, number: int) -> Issue:
"""Read an issue or PR body (read-anywhere)."""
didericis commented 2026-07-01 08:03:43 -04:00
Owner
Copy Link
Copy Source

Should be a separate “read_pr” method

Should be a separate “read_pr” method
didericis marked this conversation as resolved
didericis reviewed 2026-07-01 08:11:26 -04:00
bot_bottle/contrib/gitea/forge_state.py Outdated
@@ -0,0 +5,4 @@
freeze / rehydrate loop, and run the watchdog. State lives on disk and
survives orchestrator restarts:
~/.bot-bottle/forge/<owner>/<repo>/issue-<n>.json
didericis commented 2026-07-01 08:11:25 -04:00
Owner
Copy Link
Copy Source

We should introduce sqlite and start writing state in a local db now. We should do it the following way:

  1. db lives in the home ~/.bot-bottle folder
  2. there’s a thin api for performing crud against the db so we can swap out different storage locations
We should introduce sqlite and start writing state in a local db now. We should do it the following way: 1. db lives in the home ~/.bot-bottle folder 2. there’s a thin api for performing crud against the db so we can swap out different storage locations
didericis reviewed 2026-07-01 08:12:01 -04:00
bot_bottle/contrib/gitea/provenance.py Outdated
@@ -0,0 +1,103 @@
"""Provenance footer (PRD forge-native-integration, chunk 5).
Every orchestrator-posted comment ends with this footer — non-optional
and not configurable off. It renders the run's audit trail (agent,
didericis commented 2026-07-01 08:12:00 -04:00
Owner
Copy Link
Copy Source

Get rid of the provenance footer

Get rid of the provenance footer
didericis reviewed 2026-07-01 08:13:44 -04:00
docs/prds/prd-new-forge-native-integration.md
@@ -0,0 +447,4 @@
alongside the agent for forge-targeted runs. Tests: arg parsing, `start`
delegates to `start --headless`, `resume` delegates to `resume --headless`.
## Provenance as the product
didericis commented 2026-07-01 08:13:44 -04:00
Owner
Copy Link
Copy Source

Reword this: we will have a provenance api, but we won’t surface it in the pr

Reword this: we will have a provenance api, but we won’t surface it in the pr
didericis added 1 commit 2026-07-01 08:37:30 -04:00
refactor(forge): address PR #318 review — PR/Issue split, sqlite state, drop footer
lint / lint (push) Successful in 1m59s
Details
test / unit (pull_request) Successful in 54s
Details
test / integration (pull_request) Successful in 19s
Details
test / coverage (pull_request) Successful in 1m4s
Details
42004d37fd 
Addresses the five review comments on PR #318:

- Split PullRequest from Issue and add a dedicated read_pr method on
  Forge/ScopedForge/GiteaForge (a PR carries merge state an issue does
  not); is_pr_open now derives from read_pr.
- Replace the JSON-file forge state with a thin swappable CRUD interface
  (ForgeStateStore) backed by SQLite (SqliteForgeStateStore) at
  ~/.bot-bottle/bot-bottle.db.
- Remove the provenance footer (provenance.py + its test): a mutable,
  unsigned PR comment is not an audit record.
- Reword the PRD: provenance is exposed via an API, not surfaced in the
  PR; document the Issue/PullRequest split and the SQLite store.

pyright clean (whole repo), pylint 10/10, 38 forge/resume unit tests pass;
no remaining refs to the removed provenance module or old JSON state API.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WL77TgFxKbs3cidGMG9dz7
didericis-claude commented 2026-07-01 08:37:55 -04:00
Author
Collaborator
Copy Link
Copy Source

Addressed the review in commit 42004d3:

  • PullRequest dataclass + read_pr — Issue and PullRequest are now separate frozen dataclasses (a PR carries merged), read through separate read_issue / read_pr methods on Forge / ScopedForge / GiteaForge. is_pr_open now derives from read_pr.
  • SQLite state — replaced the JSON-file store with a thin swappable CRUD interface ForgeStateStore (upsert/get/delete/all), backed by SqliteForgeStateStore at ~/.bot-bottle/bot-bottle.db. Storage location/engine is swappable behind the interface.
  • Provenance footer removed — deleted provenance.py and its test.
  • PRD reworded — provenance is now described as a provenance API (not surfaced in the PR); also documents the Issue/PullRequest split and the SQLite store.

pyright clean (whole repo), pylint 10/10, forge/resume unit tests pass.

Addressed the review in commit 42004d3: - **`PullRequest` dataclass + `read_pr`** — `Issue` and `PullRequest` are now separate frozen dataclasses (a PR carries `merged`), read through separate `read_issue` / `read_pr` methods on `Forge` / `ScopedForge` / `GiteaForge`. `is_pr_open` now derives from `read_pr`. - **SQLite state** — replaced the JSON-file store with a thin swappable CRUD interface `ForgeStateStore` (upsert/get/delete/all), backed by `SqliteForgeStateStore` at `~/.bot-bottle/bot-bottle.db`. Storage location/engine is swappable behind the interface. - **Provenance footer removed** — deleted `provenance.py` and its test. - **PRD reworded** — provenance is now described as a provenance **API** (not surfaced in the PR); also documents the Issue/PullRequest split and the SQLite store. pyright clean (whole repo), pylint 10/10, forge/resume unit tests pass.
didericis force-pushed forge-native-integration from 83cb64378c to 42004d37fd 2026-07-01 11:17:25 -04:00 Compare
didericis added 1 commit 2026-07-01 13:11:21 -04:00
feat: expose stable Python API for programmatic bottle orchestration
lint / lint (push) Failing after 2m1s
Details
test / unit (pull_request) Successful in 50s
Details
test / integration (pull_request) Successful in 18s
Details
test / coverage (pull_request) Failing after 1m8s
Details
520e6f545d 
Add bot_bottle/api.py with four public functions the orchestrator uses:
start_headless, resume_headless, freeze, and destroy. These let a
ProgrammaticBottleRunner call directly into bot_bottle instead of
shelling out to the CLI; call sites in lifecycle.py stay unchanged.

Key changes:
- BottleSpec gains forge_env field for forge sidecar credentials
- _launch_bottle returns (slug, exit_code) instead of int so start_headless
  can return the slug to callers
- All four API functions convert Die and non-zero exits to BottleError
- 27 new unit tests; existing tests updated for the new return type

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
didericis-claude commented 2026-07-01 13:11:45 -04:00
Author
Collaborator
Copy Link
Copy Source

Added bot_bottle/api.py with the stable Python API the orchestrator needs for a ProgrammaticBottleRunner:

# bot_bottle now exports:
from bot_bottle import start_headless, resume_headless, freeze, destroy, BottleError

What changed:

  • BottleSpec.forge_env — new field carries forge sidecar env vars through to the backend. Defaults to {} for non-forge runs; the forge sidecar (chunk 4) will pick it up at launch time.

  • _launch_bottle returns (slug, exit_code) instead of always-0 int. The slug lets start_headless() hand it back to the orchestrator; the real exit code lets the API convert non-zero to BottleError. CLI callers unpack and return just the exit code — no behaviour change for operators.

  • bot_bottle/api.py — four public functions:

    • start_headless(agent, *, prompt, bottles, forge_env, ...) → slug
    • resume_headless(slug, *, prompt, forge_env, ...) → None
    • freeze(slug, *, backend_name) → None
    • destroy(slug, *, backend_name) → None (brings down compose project + removes state dir; idempotent)

    All four convert Die and non-zero exits to BottleError(message, exit_code=N).

  • 27 new unit tests in tests/unit/test_api.py; existing headless tests updated for the new return type.

forge_env is stored on BottleSpec and threaded into start_headless/resume_headless, but not yet consumed — chunk 4 (forge sidecar) will read spec.forge_env to inject into the sidecar container at launch time.

Added `bot_bottle/api.py` with the stable Python API the orchestrator needs for a `ProgrammaticBottleRunner`: ```python # bot_bottle now exports: from bot_bottle import start_headless, resume_headless, freeze, destroy, BottleError ``` **What changed:** - **`BottleSpec.forge_env`** — new field carries forge sidecar env vars through to the backend. Defaults to `{}` for non-forge runs; the forge sidecar (chunk 4) will pick it up at launch time. - **`_launch_bottle` returns `(slug, exit_code)`** instead of always-0 `int`. The slug lets `start_headless()` hand it back to the orchestrator; the real exit code lets the API convert non-zero to `BottleError`. CLI callers unpack and return just the exit code — no behaviour change for operators. - **`bot_bottle/api.py`** — four public functions: - `start_headless(agent, *, prompt, bottles, forge_env, ...)` → slug - `resume_headless(slug, *, prompt, forge_env, ...)` → None - `freeze(slug, *, backend_name)` → None - `destroy(slug, *, backend_name)` → None (brings down compose project + removes state dir; idempotent) All four convert `Die` and non-zero exits to `BottleError(message, exit_code=N)`. - **27 new unit tests** in `tests/unit/test_api.py`; existing headless tests updated for the new return type. `forge_env` is stored on `BottleSpec` and threaded into `start_headless`/`resume_headless`, but not yet consumed — chunk 4 (forge sidecar) will read `spec.forge_env` to inject into the sidecar container at launch time.
Some checks are pending
lint / lint (push) Failing after 2m1s
Details
test / unit (pull_request) Successful in 50s
Details
test / integration (pull_request) Successful in 18s
Details
test / coverage (pull_request) Failing after 1m8s
Details
This pull request can be merged automatically.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin forge-native-integration:forge-native-integration
git checkout forge-native-integration
Sign in to join this conversation.
Reviewers
No Reviewers
didericis
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
didericis-claude (didericis (claude)) didericis-codex (didericis (codex)) didericis-gemma (gemma) didericis
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: didericis/bot-bottle#318
Delete Branch "forge-native-integration"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?