feat(memory-gateway): merge memory mode with main
This commit is contained in:
338
docs/superpowers/plans/2026-06-15-hybrid-memory-gateway.md
Normal file
338
docs/superpowers/plans/2026-06-15-hybrid-memory-gateway.md
Normal file
@ -0,0 +1,338 @@
|
||||
# Hybrid Memory Gateway Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Preserve Beaver curated memory while adding an isolated, best-effort Memory Gateway recall and per-turn persistence layer enabled by hybrid configuration.
|
||||
|
||||
**Architecture:** Curated `MemoryService`, frozen snapshots, and the `memory` tool remain unconditional. A new optional `MemoryGatewayService` wraps a small async HTTP client and is attached by `EngineLoader` only when hybrid configuration is valid. `AgentLoop` conditionally adds Gateway recall before provider execution and add/flush after normal completion without copying data between the two stores.
|
||||
|
||||
**Tech Stack:** Python 3.11, dataclasses, httpx, SQLite-backed session audit events, pytest/pytest-asyncio.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Add typed hybrid memory configuration
|
||||
|
||||
**Files:**
|
||||
- Modify: `app-instance/backend/beaver/foundation/config/schema.py`
|
||||
- Modify: `app-instance/backend/beaver/foundation/config/loader.py`
|
||||
- Modify: `app-instance/backend/beaver/foundation/config/__init__.py`
|
||||
- Modify: `app-instance/backend/tests/unit/test_config_loader.py`
|
||||
|
||||
- [ ] **Step 1: Write failing configuration tests**
|
||||
|
||||
Add tests covering implicit hybrid defaults, explicit curated, complete explicit hybrid, invalid modes/scopes/ranges, and explicit hybrid missing credentials. Assert secret values never appear in errors.
|
||||
|
||||
```python
|
||||
def test_missing_memory_config_defaults_to_implicit_hybrid(tmp_path):
|
||||
config = load_config(config_path=tmp_path / "missing.json")
|
||||
assert config.memory.mode == "hybrid"
|
||||
assert config.memory.explicit is False
|
||||
|
||||
def test_explicit_hybrid_requires_gateway_credentials(tmp_path):
|
||||
path = tmp_path / "config.json"
|
||||
path.write_text('{"memory":{"mode":"hybrid","gateway":{"userKey":"secret"}}}')
|
||||
with pytest.raises(ValueError) as exc:
|
||||
load_config(config_path=path)
|
||||
assert "secret" not in str(exc.value)
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run configuration tests and verify RED**
|
||||
|
||||
Run: `uv run pytest -q tests/unit/test_config_loader.py`
|
||||
|
||||
Expected: failures because `BeaverConfig.memory` and memory parsing do not exist.
|
||||
|
||||
- [ ] **Step 3: Implement minimal typed configuration**
|
||||
|
||||
Add `MemoryGatewayConfig` and `MemoryConfig` dataclasses. Mark `user_key` with `repr=False`. Parse camelCase/snake_case fields, preserve `explicit`, and validate the confirmed rules.
|
||||
|
||||
```python
|
||||
@dataclass(slots=True)
|
||||
class MemoryGatewayConfig:
|
||||
base_url: str = ""
|
||||
user_id: str = ""
|
||||
user_key: str = field(default="", repr=False)
|
||||
app_id: str = "default"
|
||||
project_id: str = "default"
|
||||
scope: list[str] = field(default_factory=lambda: ["current_chat", "resources"])
|
||||
top_k: int = 8
|
||||
timeout_seconds: float = 10.0
|
||||
|
||||
@dataclass(slots=True)
|
||||
class MemoryConfig:
|
||||
mode: str = "hybrid"
|
||||
explicit: bool = False
|
||||
gateway: MemoryGatewayConfig = field(default_factory=MemoryGatewayConfig)
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run configuration tests and verify GREEN**
|
||||
|
||||
Run: `uv run pytest -q tests/unit/test_config_loader.py`
|
||||
|
||||
Expected: all tests pass.
|
||||
|
||||
- [ ] **Step 5: Commit configuration support**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/beaver/foundation/config app-instance/backend/tests/unit/test_config_loader.py
|
||||
git commit -m "feat(memory): add hybrid gateway configuration"
|
||||
```
|
||||
|
||||
### Task 2: Implement the Memory Gateway client and isolated service
|
||||
|
||||
**Files:**
|
||||
- Create: `app-instance/backend/beaver/integrations/memory_gateway/__init__.py`
|
||||
- Create: `app-instance/backend/beaver/integrations/memory_gateway/client.py`
|
||||
- Create: `app-instance/backend/beaver/services/memory_gateway_service.py`
|
||||
- Modify: `app-instance/backend/beaver/services/__init__.py`
|
||||
- Create: `app-instance/backend/tests/unit/test_memory_gateway_service.py`
|
||||
|
||||
- [ ] **Step 1: Write failing client/service tests**
|
||||
|
||||
Test exact search/add/flush paths and payloads, result sanitization, empty recall, add-failure skipping flush, flush failure reporting, and secret-free errors. Use a fake client for service tests and monkeypatch `httpx.AsyncClient` for transport tests.
|
||||
|
||||
```python
|
||||
@pytest.mark.asyncio
|
||||
async def test_persist_after_run_adds_two_messages_then_flushes():
|
||||
client = FakeGatewayClient()
|
||||
service = MemoryGatewayService(config, client=client)
|
||||
outcome = await service.persist_after_run(
|
||||
session_id="web:alpha",
|
||||
user_text="hello",
|
||||
assistant_text="hi",
|
||||
user_timestamp_ms=1000,
|
||||
assistant_timestamp_ms=1001,
|
||||
)
|
||||
assert outcome.add_succeeded is True
|
||||
assert outcome.flush_succeeded is True
|
||||
assert [call[0] for call in client.calls] == ["add", "flush"]
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run service tests and verify RED**
|
||||
|
||||
Run: `uv run pytest -q tests/unit/test_memory_gateway_service.py`
|
||||
|
||||
Expected: import failure because the integration and service do not exist.
|
||||
|
||||
- [ ] **Step 3: Implement the minimal async client**
|
||||
|
||||
Create `MemoryGatewayClient` with `search`, `add`, and `flush`. Raise `MemoryGatewayClientError(operation, category, status_code)` without embedding request bodies or credentials.
|
||||
|
||||
```python
|
||||
async def search(self, payload: dict[str, Any]) -> dict[str, Any]:
|
||||
return await self._post("search", "/memories/search", payload)
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Implement the isolated Gateway service**
|
||||
|
||||
Create typed recall/persist outcome dataclasses. The service builds configured payloads, strips result fields to the approved allowlist, renders one reference message, and never imports or calls `MemoryStore`.
|
||||
|
||||
```python
|
||||
@dataclass(slots=True)
|
||||
class GatewayRecallOutcome:
|
||||
reference_messages: list[dict[str, str]] = field(default_factory=list)
|
||||
result_count: int = 0
|
||||
error: MemoryGatewayClientError | None = None
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Run service tests and verify GREEN**
|
||||
|
||||
Run: `uv run pytest -q tests/unit/test_memory_gateway_service.py`
|
||||
|
||||
Expected: all tests pass.
|
||||
|
||||
- [ ] **Step 6: Commit client and service**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/beaver/integrations/memory_gateway app-instance/backend/beaver/services app-instance/backend/tests/unit/test_memory_gateway_service.py
|
||||
git commit -m "feat(memory): add memory gateway client and service"
|
||||
```
|
||||
|
||||
### Task 3: Extend context assembly for ephemeral Gateway recall
|
||||
|
||||
**Files:**
|
||||
- Modify: `app-instance/backend/beaver/engine/context/builder.py`
|
||||
- Modify: `app-instance/backend/tests/unit/test_context_builder.py`
|
||||
|
||||
- [ ] **Step 1: Write failing context ordering tests**
|
||||
|
||||
Verify reference messages appear after activated skill messages and before persisted history/current user input, while recalled text is absent from the system prompt.
|
||||
|
||||
```python
|
||||
def test_context_builder_places_reference_messages_before_history():
|
||||
result = ContextBuilder().build_messages(ContextBuildInput(
|
||||
reference_messages=[{"role": "user", "content": "[MEMORY REFERENCE] old fact"}],
|
||||
history=[{"role": "assistant", "content": "prior reply"}],
|
||||
current_user_input="new question",
|
||||
))
|
||||
assert result.messages[-3:] == [
|
||||
{"role": "user", "content": "[MEMORY REFERENCE] old fact"},
|
||||
{"role": "assistant", "content": "prior reply"},
|
||||
{"role": "user", "content": "new question"},
|
||||
]
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run context tests and verify RED**
|
||||
|
||||
Run: `uv run pytest -q tests/unit/test_context_builder.py`
|
||||
|
||||
Expected: `ContextBuildInput` rejects `reference_messages`.
|
||||
|
||||
- [ ] **Step 3: Implement reference message support**
|
||||
|
||||
Add `reference_messages` to `ContextBuildInput` and append normalized non-system messages immediately after skill activation messages.
|
||||
|
||||
- [ ] **Step 4: Run context tests and verify GREEN**
|
||||
|
||||
Run: `uv run pytest -q tests/unit/test_context_builder.py`
|
||||
|
||||
Expected: all tests pass.
|
||||
|
||||
- [ ] **Step 5: Commit context support**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/beaver/engine/context/builder.py app-instance/backend/tests/unit/test_context_builder.py
|
||||
git commit -m "feat(memory): support ephemeral gateway recall context"
|
||||
```
|
||||
|
||||
### Task 4: Wire the optional Gateway service into EngineLoader
|
||||
|
||||
**Files:**
|
||||
- Modify: `app-instance/backend/beaver/engine/loader.py`
|
||||
- Modify: `app-instance/backend/tests/unit/test_imports.py`
|
||||
- Create: `app-instance/backend/tests/unit/test_memory_gateway_loader.py`
|
||||
|
||||
- [ ] **Step 1: Write failing loader tests**
|
||||
|
||||
Cover explicit curated, explicit valid hybrid, implicit hybrid degradation with a sanitized warning, and explicit invalid hybrid rejection. Assert curated store and `memory` tool are present in every successful mode.
|
||||
|
||||
- [ ] **Step 2: Run loader tests and verify RED**
|
||||
|
||||
Run: `uv run pytest -q tests/unit/test_imports.py tests/unit/test_memory_gateway_loader.py`
|
||||
|
||||
Expected: failures because `EngineLoadResult.memory_gateway_service` does not exist.
|
||||
|
||||
- [ ] **Step 3: Implement loader wiring**
|
||||
|
||||
Add optional dependency injection and result fields for `MemoryGatewayService`. Always initialize curated memory and register `MemoryTool`; initialize Gateway only for valid hybrid configuration. Log one warning when implicit hybrid lacks credentials.
|
||||
|
||||
```python
|
||||
memory_gateway_service = self._memory_gateway_service
|
||||
if memory_gateway_service is None and config.memory.mode == "hybrid":
|
||||
if config.memory.gateway.is_configured:
|
||||
memory_gateway_service = MemoryGatewayService(config.memory.gateway)
|
||||
elif not config.memory.explicit:
|
||||
logger.warning("Memory Gateway is not configured; continuing with curated memory only")
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run loader tests and verify GREEN**
|
||||
|
||||
Run: `uv run pytest -q tests/unit/test_imports.py tests/unit/test_memory_gateway_loader.py`
|
||||
|
||||
Expected: all tests pass.
|
||||
|
||||
- [ ] **Step 5: Commit loader wiring**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/beaver/engine/loader.py app-instance/backend/tests/unit/test_imports.py app-instance/backend/tests/unit/test_memory_gateway_loader.py
|
||||
git commit -m "feat(memory): initialize optional gateway layer"
|
||||
```
|
||||
|
||||
### Task 5: Integrate Gateway recall, persistence, and audit events into AgentLoop
|
||||
|
||||
**Files:**
|
||||
- Modify: `app-instance/backend/beaver/engine/loop.py`
|
||||
- Create: `app-instance/backend/tests/unit/test_memory_gateway_agent_loop.py`
|
||||
|
||||
- [ ] **Step 1: Write failing successful-flow AgentLoop test**
|
||||
|
||||
Use a fake provider and injected fake Gateway service. Verify curated snapshot remains in the system prompt, Gateway recall is outside it and before the current user prompt, and add/flush persistence receives only the original user and final assistant text.
|
||||
|
||||
- [ ] **Step 2: Run the successful-flow test and verify RED**
|
||||
|
||||
Run: `uv run pytest -q tests/unit/test_memory_gateway_agent_loop.py::test_hybrid_run_keeps_curated_memory_and_persists_gateway_turn`
|
||||
|
||||
Expected: failure because `AgentLoop` does not call the Gateway service.
|
||||
|
||||
- [ ] **Step 3: Implement pre-run recall and success audit**
|
||||
|
||||
When `loaded.memory_gateway_service` exists, call recall before context assembly, append hidden success/failure events, pass returned reference messages into `ContextBuildInput`, and add the stable untrusted-reference rule through `extra_sections`.
|
||||
|
||||
- [ ] **Step 4: Implement post-run persistence and audit**
|
||||
|
||||
Capture positive millisecond timestamps, call `persist_after_run` after final text is known and before returning, and append hidden add/flush success/failure events. Do not invoke persistence in the exception path.
|
||||
|
||||
- [ ] **Step 5: Add failing failure-path tests**
|
||||
|
||||
Cover recall failure, add failure, and flush failure. Assert the returned `AgentRunResult` is unchanged, curated snapshot remains present, add failure skips flush, and audit payloads contain no configured key.
|
||||
|
||||
- [ ] **Step 6: Run AgentLoop tests and verify GREEN**
|
||||
|
||||
Run: `uv run pytest -q tests/unit/test_memory_gateway_agent_loop.py tests/unit/test_agent_loop.py tests/unit/test_agent_team_v1.py`
|
||||
|
||||
Expected: all tests pass.
|
||||
|
||||
- [ ] **Step 7: Commit AgentLoop integration**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/beaver/engine/loop.py app-instance/backend/tests/unit/test_memory_gateway_agent_loop.py
|
||||
git commit -m "feat(memory): add hybrid gateway runtime flow"
|
||||
```
|
||||
|
||||
### Task 6: Document configuration and run full verification
|
||||
|
||||
**Files:**
|
||||
- Modify: `app-instance/backend/README.md`
|
||||
- Modify: `app-instance/backend/env_template` if it contains runtime config guidance
|
||||
|
||||
- [ ] **Step 1: Update backend documentation**
|
||||
|
||||
Document implicit hybrid mode, explicit curated mode, full hybrid JSON configuration, degradation/validation behavior, restart requirement, and the secrecy of `userKey`.
|
||||
|
||||
- [ ] **Step 2: Run targeted tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
uv run pytest -q \
|
||||
tests/unit/test_config_loader.py \
|
||||
tests/unit/test_memory_gateway_service.py \
|
||||
tests/unit/test_context_builder.py \
|
||||
tests/unit/test_memory_gateway_loader.py \
|
||||
tests/unit/test_memory_gateway_agent_loop.py \
|
||||
tests/unit/test_imports.py \
|
||||
tests/unit/test_agent_loop.py
|
||||
```
|
||||
|
||||
Expected: all targeted tests pass.
|
||||
|
||||
- [ ] **Step 3: Run the backend unit suite**
|
||||
|
||||
Run: `uv run pytest -q tests/unit`
|
||||
|
||||
Expected: all unit tests pass.
|
||||
|
||||
- [ ] **Step 4: Compile changed Python packages**
|
||||
|
||||
Run: `uv run python -m compileall -q beaver tests/unit`
|
||||
|
||||
Expected: exit code 0 with no output.
|
||||
|
||||
- [ ] **Step 5: Review secret handling and diff**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
git diff --check
|
||||
rg -n "userKey|user_key" app-instance/backend/beaver app-instance/backend/tests/unit/test_memory_gateway* app-instance/backend/README.md
|
||||
git status --short
|
||||
```
|
||||
|
||||
Expected: credentials appear only as field names or test fixtures; no real key is logged or committed.
|
||||
|
||||
- [ ] **Step 6: Commit documentation and verification adjustments**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/README.md app-instance/backend/env_template
|
||||
git commit -m "docs(memory): document hybrid gateway configuration"
|
||||
```
|
||||
@ -0,0 +1,265 @@
|
||||
# Memory Gateway User Provisioning Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Move Beaver's Gateway code into `beaver.memory.gateway`, load one shared non-secret Gateway configuration, provision Gateway users during Beaver registration, and resolve per-user credentials for each authenticated chat run.
|
||||
|
||||
**Architecture:** `EngineLoader` loads curated memory, a shared Gateway config, and an instance-local credential store. Registration calls Gateway `/users` and atomically stores credentials by Beaver username. REST/WebSocket chat derive a trusted username from the access token and `AgentLoop` creates a run-local Gateway service for that user, leaving unauthenticated or unprovisioned runs on curated memory only.
|
||||
|
||||
**Tech Stack:** Python 3.14, dataclasses, FastAPI, httpx, pytest, shell-based Docker instance creation.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Move Gateway source and load shared configuration
|
||||
|
||||
**Files:**
|
||||
- Create: `app-instance/backend/beaver/memory/gateway/__init__.py`
|
||||
- Create: `app-instance/backend/beaver/memory/gateway/config.py`
|
||||
- Create: `app-instance/backend/beaver/memory/gateway/client.py`
|
||||
- Create: `app-instance/backend/beaver/memory/gateway/service.py`
|
||||
- Create: `app-instance/backend/memory/config.json`
|
||||
- Modify: `app-instance/backend/beaver/foundation/config/schema.py`
|
||||
- Modify: `app-instance/backend/beaver/foundation/config/loader.py`
|
||||
- Modify: `app-instance/backend/beaver/foundation/config/__init__.py`
|
||||
- Delete: `app-instance/backend/beaver/integrations/memory_gateway/`
|
||||
- Delete: `app-instance/backend/beaver/services/memory_gateway_service.py`
|
||||
- Modify: `app-instance/backend/beaver/services/__init__.py`
|
||||
- Test: `app-instance/backend/tests/unit/test_config_loader.py`
|
||||
- Test: `app-instance/backend/tests/unit/test_memory_gateway_service.py`
|
||||
|
||||
- [ ] **Step 1: Write failing shared-config and import tests**
|
||||
|
||||
Set `BEAVER_MEMORY_CONFIG_PATH` to a temporary JSON file and assert `load_config()` obtains `memory.mode`, URL, and all three scopes from that file. Change all Gateway tests to import from `beaver.memory.gateway`.
|
||||
|
||||
- [ ] **Step 2: Run tests and verify RED**
|
||||
|
||||
```bash
|
||||
cd app-instance/backend
|
||||
.venv/bin/pytest -q tests/unit/test_config_loader.py tests/unit/test_memory_gateway_service.py
|
||||
```
|
||||
|
||||
Expected: failures because the new package and shared config loading do not exist.
|
||||
|
||||
- [ ] **Step 3: Implement package migration and shared config parsing**
|
||||
|
||||
Move existing client/service behavior without changing payloads. Define `MemoryConfig` and `MemoryGatewayConfig` in `beaver.memory.gateway.config`, without `userId/userKey`. Add `default_memory_config_path()` using `BEAVER_MEMORY_CONFIG_PATH` then `<backend-root>/memory/config.json`. Instance config parsing remains responsible for non-memory settings; shared config supplies `BeaverConfig.memory`.
|
||||
|
||||
Create tracked `memory/config.json` with `http://172.19.207.37:8010`, scopes `current_chat`, `resources`, `all_user_memory`, top K 8, and timeout 10.
|
||||
|
||||
- [ ] **Step 4: Run targeted tests and verify GREEN**
|
||||
|
||||
Run the command from Step 2. Expected: selected tests pass.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/beaver/memory/gateway app-instance/backend/memory/config.json app-instance/backend/beaver/foundation/config app-instance/backend/beaver/services app-instance/backend/tests/unit/test_config_loader.py app-instance/backend/tests/unit/test_memory_gateway_service.py
|
||||
git commit -m "refactor(memory): move gateway into memory domain"
|
||||
```
|
||||
|
||||
### Task 2: Add per-instance Gateway credential storage
|
||||
|
||||
**Files:**
|
||||
- Create: `app-instance/backend/beaver/memory/gateway/credentials.py`
|
||||
- Modify: `app-instance/backend/beaver/memory/gateway/__init__.py`
|
||||
- Create: `app-instance/backend/tests/unit/test_memory_gateway_credentials.py`
|
||||
- Modify: `app-instance/create-instance.sh`
|
||||
- Modify: `app-instance/entrypoint.sh`
|
||||
- Modify: `app-instance/README.md`
|
||||
|
||||
- [ ] **Step 1: Write failing credential-store tests**
|
||||
|
||||
Cover missing files, multi-user round trips, updates preserving other users, secret-free repr, atomic replace, and mode `0600`.
|
||||
|
||||
- [ ] **Step 2: Run test and verify RED**
|
||||
|
||||
```bash
|
||||
cd app-instance/backend
|
||||
.venv/bin/pytest -q tests/unit/test_memory_gateway_credentials.py
|
||||
```
|
||||
|
||||
Expected: import failure because the credential store does not exist.
|
||||
|
||||
- [ ] **Step 3: Implement atomic credential persistence**
|
||||
|
||||
Implement `MemoryGatewayUserCredential(user_id, user_key)` and `MemoryGatewayCredentialStore.get/save`. Use JSON shape `{"users": {username: {"userId": ..., "userKey": ...}}}`, sibling temporary file, `os.replace`, and `chmod(0o600)`.
|
||||
|
||||
Update `create-instance.sh` to create `$BEAVER_HOME/memory_gateway_users.json` as `{"users": {}}`, chmod it `0600`, and pass `BEAVER_MEMORY_GATEWAY_USERS_PATH=/root/.beaver/memory_gateway_users.json`. `entrypoint.sh` exports the same default.
|
||||
|
||||
- [ ] **Step 4: Run credential and shell syntax tests**
|
||||
|
||||
```bash
|
||||
cd app-instance/backend
|
||||
.venv/bin/pytest -q tests/unit/test_memory_gateway_credentials.py
|
||||
cd ../..
|
||||
bash -n app-instance/create-instance.sh app-instance/entrypoint.sh
|
||||
```
|
||||
|
||||
Expected: tests pass and shell syntax exits zero.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/beaver/memory/gateway app-instance/backend/tests/unit/test_memory_gateway_credentials.py app-instance/create-instance.sh app-instance/entrypoint.sh app-instance/README.md
|
||||
git commit -m "feat(memory): persist gateway user credentials"
|
||||
```
|
||||
|
||||
### Task 3: Provision Gateway identities during frontend registration
|
||||
|
||||
**Files:**
|
||||
- Modify: `app-instance/backend/beaver/memory/gateway/client.py`
|
||||
- Modify: `app-instance/backend/beaver/interfaces/web/app.py`
|
||||
- Create: `app-instance/backend/tests/unit/test_memory_gateway_registration.py`
|
||||
|
||||
- [ ] **Step 1: Write failing registration tests**
|
||||
|
||||
Use a temporary auth file and fake Gateway client. Assert registration sends `{"user_id": "tom"}`, stores the returned key, never returns the key to the browser, and still registers the Beaver user without a partial credential when Gateway provisioning fails.
|
||||
|
||||
- [ ] **Step 2: Run tests and verify RED**
|
||||
|
||||
```bash
|
||||
cd app-instance/backend
|
||||
.venv/bin/pytest -q tests/unit/test_memory_gateway_registration.py
|
||||
```
|
||||
|
||||
Expected: failures because `/users` provisioning is not connected.
|
||||
|
||||
- [ ] **Step 3: Implement provisioning**
|
||||
|
||||
Add `MemoryGatewayClient.create_user(user_id)`, validating non-empty response `user_id/user_key`. During `/api/auth/register`, after local/AuthZ registration succeeds, call it with the Beaver username and save through the credential store. Catch sanitized Gateway failures without retrying or rolling back Beaver registration. Never include the Gateway credential in the response.
|
||||
|
||||
- [ ] **Step 4: Run registration tests and verify GREEN**
|
||||
|
||||
Run the command from Step 2. Expected: all registration tests pass.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/beaver/memory/gateway/client.py app-instance/backend/beaver/interfaces/web/app.py app-instance/backend/tests/unit/test_memory_gateway_registration.py
|
||||
git commit -m "feat(memory): provision gateway users on registration"
|
||||
```
|
||||
|
||||
### Task 4: Pass trusted authenticated identity into chat runs
|
||||
|
||||
**Files:**
|
||||
- Modify: `app-instance/backend/beaver/interfaces/web/app.py`
|
||||
- Modify: `app-instance/backend/beaver/engine/loop.py`
|
||||
- Modify: `app-instance/backend/beaver/services/agent_service.py`
|
||||
- Modify: `app-instance/backend/tests/unit/test_websocket_chat.py`
|
||||
|
||||
- [ ] **Step 1: Write failing REST/WebSocket identity tests**
|
||||
|
||||
Issue a web token for `tom`. Assert REST and WebSocket calls pass `gateway_user_id="tom"`. Send a conflicting client `user_id="other"` and assert the trusted identity remains `tom`. Unauthenticated calls pass `gateway_user_id=None`.
|
||||
|
||||
- [ ] **Step 2: Run tests and verify RED**
|
||||
|
||||
```bash
|
||||
cd app-instance/backend
|
||||
.venv/bin/pytest -q tests/unit/test_websocket_chat.py
|
||||
```
|
||||
|
||||
Expected: identity assertions fail because chat does not pass a trusted Gateway principal.
|
||||
|
||||
- [ ] **Step 3: Implement optional trusted identity resolution**
|
||||
|
||||
Add `gateway_user_id: str | None` to AgentLoop direct-run kwargs. REST reads the optional bearer token from `Authorization`; WebSocket reads the existing `?token=` parameter. Both resolve only through `app.state.auth_tokens`. Request `user_id` remains session metadata and never selects Gateway credentials.
|
||||
|
||||
- [ ] **Step 4: Run identity tests and verify GREEN**
|
||||
|
||||
Run the command from Step 2. Expected: tests pass.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/beaver/interfaces/web/app.py app-instance/backend/beaver/engine/loop.py app-instance/backend/beaver/services/agent_service.py app-instance/backend/tests/unit/test_websocket_chat.py
|
||||
git commit -m "feat(memory): bind gateway runs to authenticated users"
|
||||
```
|
||||
|
||||
### Task 5: Resolve a run-local Gateway service per user
|
||||
|
||||
**Files:**
|
||||
- Modify: `app-instance/backend/beaver/engine/loader.py`
|
||||
- Modify: `app-instance/backend/beaver/engine/loop.py`
|
||||
- Modify: `app-instance/backend/beaver/memory/gateway/service.py`
|
||||
- Modify: `app-instance/backend/tests/unit/test_memory_gateway_loader.py`
|
||||
- Modify: `app-instance/backend/tests/unit/test_memory_gateway_agent_loop.py`
|
||||
|
||||
- [ ] **Step 1: Write failing loader and AgentLoop tests**
|
||||
|
||||
Assert loader exposes shared config, credential store, and service factory instead of a fixed-user service. Add two users with different keys and verify each run constructs a service from only the selected credential. Missing identity or credential performs no Gateway calls while curated memory remains present.
|
||||
|
||||
- [ ] **Step 2: Run tests and verify RED**
|
||||
|
||||
```bash
|
||||
cd app-instance/backend
|
||||
.venv/bin/pytest -q tests/unit/test_memory_gateway_loader.py tests/unit/test_memory_gateway_agent_loop.py
|
||||
```
|
||||
|
||||
Expected: failures because loader still creates one fixed-user service.
|
||||
|
||||
- [ ] **Step 3: Implement per-run service resolution**
|
||||
|
||||
Expose `memory_gateway_config`, `memory_gateway_credentials`, and a service factory on `EngineLoadResult`. At run start, resolve the credential by `gateway_user_id`; construct a fresh service only in hybrid mode when a credential exists. Pass shared config and credential separately to the service and preserve current recall/add/flush/audit behavior.
|
||||
|
||||
- [ ] **Step 4: Run Gateway runtime tests and verify GREEN**
|
||||
|
||||
```bash
|
||||
cd app-instance/backend
|
||||
.venv/bin/pytest -q tests/unit/test_memory_gateway_loader.py tests/unit/test_memory_gateway_agent_loop.py tests/unit/test_memory_gateway_service.py tests/unit/test_context_builder.py
|
||||
```
|
||||
|
||||
Expected: all selected tests pass.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/beaver/engine app-instance/backend/beaver/memory/gateway app-instance/backend/tests/unit/test_memory_gateway_loader.py app-instance/backend/tests/unit/test_memory_gateway_agent_loop.py
|
||||
git commit -m "feat(memory): resolve gateway service per user"
|
||||
```
|
||||
|
||||
### Task 6: Update documentation and perform final verification
|
||||
|
||||
**Files:**
|
||||
- Modify: `app-instance/backend/README.md`
|
||||
- Modify: `app-instance/README.md`
|
||||
- Modify: `docs/superpowers/plans/2026-06-15-hybrid-memory-gateway.md`
|
||||
|
||||
- [ ] **Step 1: Update operational documentation**
|
||||
|
||||
Document the shared config path, instance credential path, registration provisioning, token-based identity, secret handling, and rebuild/restart requirements. Remove examples that place `userId/userKey` in instance `config.json`.
|
||||
|
||||
- [ ] **Step 2: Verify removed source imports**
|
||||
|
||||
```bash
|
||||
rg -n "beaver\.integrations\.memory_gateway|beaver\.services\.memory_gateway_service" app-instance/backend/beaver app-instance/backend/tests
|
||||
```
|
||||
|
||||
Expected: no matches.
|
||||
|
||||
- [ ] **Step 3: Run full verification**
|
||||
|
||||
```bash
|
||||
cd app-instance/backend
|
||||
.venv/bin/python -m compileall -q beaver
|
||||
.venv/bin/pytest -q
|
||||
cd ../..
|
||||
bash -n app-instance/create-instance.sh app-instance/entrypoint.sh
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Expected: compile and shell checks exit zero, all tests pass, and diff check is clean.
|
||||
|
||||
- [ ] **Step 4: Scan tracked content for credentials**
|
||||
|
||||
```bash
|
||||
git grep -nE 'uk_[A-Za-z0-9]{8,}' -- ':!docs/superpowers/specs/*' ':!docs/superpowers/plans/*'
|
||||
```
|
||||
|
||||
Expected: no real Gateway key in tracked source or runtime files; obvious test placeholders are reviewed manually.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add app-instance/backend/README.md app-instance/README.md docs/superpowers/plans/2026-06-15-hybrid-memory-gateway.md
|
||||
git commit -m "docs(memory): document gateway user provisioning"
|
||||
```
|
||||
Reference in New Issue
Block a user