11 KiB
11 KiB
Pending Decisions
PD-0001: Forgejo transport for the development machine
- Status: resolved for HTTP push; SSH remains unavailable
- Current value:
ssh://git@localhost:18086/YokiiroBW/AstrBot-Desktop.git - Push URL:
http://192.168.31.210:18085/YokiiroBW/AstrBot-Desktop.git - Observation: the authenticated Forgejo API confirmed
YokiiroBW/AstrBot-Desktopexisted, was empty, usedmain, and granted push permission before initialization. - SSH observation:
localhost:18086refuses connections.192.168.31.210:18086answers but rejects the available SSH key. - Push observation: Git Credential Manager was cleared and reauthenticated without placing a secret in the repository or chat. The approved non-forced HTTP push succeeded and remote
mainnow points to0d12b94. - Decision: retain the SSH URL as the fetch URL for future key repair and use the explicitly approved HTTP URL as the push URL for this workflow.
- Safety impact: no force push or history overwrite occurred;
feat/p00-bootstrapwas created from the pushed baseline.
PD-0002: P00 branch naming
- Status: resolved for this predevelopment workflow
- Decision: use
feat/p00-bootstrapas explicitly required by the workflow and current user request. - Follow-up: subsequent stages use the branch names in
AGENTS.md.
PD-0003: Node.js release line
- Status: monitor during bootstrap
- Current environment: Node.js 24.
- Decision: use the installed version initially; pin package-manager and dependency versions in the repository and record any Tauri/Vite incompatibility found by actual builds.
PD-0004: P00 source layout
- Status: resolved for P00
- Observation: the architecture document illustrates an
apps/desktopmonorepo, while the predevelopment workflow recommends root-levelsrcandsrc-tauridirectories. - Decision: keep the single desktop application at the repository root during P00 and use Cargo workspace crates for protocol and Mock Gateway isolation.
- Reason: there is only one application, and the workflow explicitly recommends the root layout; this avoids an extra package layer without preventing a later move if a second application appears.
PD-0005: Source cleanup in the NAS Spike
- Status: resolved for P00
- Conflict: the implementation task mentions cleanup after verification, while the workflow and safety rules require source preservation and prohibit irreversible tests.
- Decision: P00 always preserves source files and tests cleanup policy only as a non-executed plan field.
- Follow-up: reversible recycle-bin behavior requires a later explicitly authorized Spike.
PD-0006: Provisional desktop gateway contract
- Status: resolved for P00
- Decision: define a provisional
desktop-v1alpha1contract and Mock Gateway without claiming compatibility with an unavailable real AstrBot Gateway. - Follow-up: authentication fields, error codes, event retention, ACK timing, and capability names require a later real-gateway contract review.
PD-0007: Repository-local Git author identity
- Status: resolved
- Decision: the user explicitly approved
YokiiroBW <yokiirobw@gmail.com>. - Implementation: the identity is configured only in this repository.
- Result: two Conventional Commit baseline commits were created on
main, pushed normally, and followed by scoped feature-branch commits. - Safety impact: no global Git identity was changed.
PD-0008: Profile CRUD stage ownership
- Status: resolved; option A selected by the project owner on 2026-07-18
- Conflict:
docs/01_Architecture_Design.mdlists Profile CRUD in stage 1, whiledocs/02_Codex_Implementation_Tasks.mdlists ConnectionProfile CRUD in Batch 2. - Decision: implement basic non-sensitive Profile metadata CRUD in P01.
- P01 scope: Profile list, create, update, and delete; SQLite schema v2; bounded Tauri IPC; strict frontend Schema; basic management UI.
- P02 scope: companion/operations slot assignment, active connection state, auto-connect validation, switching protection, and
server_instance_idconflict detection. - Secret boundary: P01 commands accept no Token, password, API Key, Cookie, Authorization header, or NAS credential fields. SQLite stores only non-sensitive metadata and future opaque credential references.
- Rationale: AGENTS.md gives the architecture document higher priority, and the selected split keeps runtime connection behavior out of P01.
- ADR:
ADR-0004-profile-lifecycle-and-secret-boundary.md.
PD-0009: Real AstrBot Desktop Gateway contract
- Status: open; does not block local slot persistence or Mock-based tests
- Current contract: repository-local
/desktop/v1and protocol1.0are provisional development contracts created during P00. - Missing authority: no reviewed real AstrBot Gateway implementation or server-side contract is available for endpoint, error-code, capability, event-retention, ACK, and authentication compatibility.
- Safe interim rule: keep the protocol types and dual Mock Gateway deterministic, but do not claim real AstrBot compatibility or silently adapt to AstrBot internal APIs.
- Stop boundary: changes that would require modifying AstrBot core or bypassing the stable Gateway boundary require explicit review.
PD-0010: Credential enrollment and token lifecycle
- Status: open before production connection activation
- Established boundary: credential values live only in Windows Credential Manager; SQLite stores opaque references; React never receives stored access or refresh tokens.
- Required decision: define enrollment/update/delete failure atomicity, whether user-entered bootstrap credentials may pass once through bounded Tauri IPC without entering React state, and how access/refresh token rotation updates secure storage.
- Safe interim rule: P02 slot persistence accepts no credential values and cannot activate a real connection.
PD-0011: Authoritative server identity enrollment
- Status: open before first real connection activation
- Candidate source:
GET /desktop/v1/server-inforeturnsserver_instance_id, matching the architecture and provisional protocol. - Required decision: define the first-contact confirmation flow, duplicate-instance warning behavior, and whether a changed identity requires a separate Profile or an explicit rebind operation.
- Safe interim rule: never overwrite an existing
server_instance_idduring background connection or reconnection.
PD-0012: TLS certificate fingerprint binding
- Status: open before enabling pinned HTTPS Profiles
- Requirement: a certificate identity change freezes local-tool permission and the affected connection; TLS validation must never be disabled.
- Required decision: select a maintained Rust TLS integration that can inspect the validated peer certificate without installing a permissive verifier, and define first-contact confirmation UX.
- Safe interim rule: preserve validated HTTPS behavior and do not claim certificate pinning until the peer certificate path is implemented and tested.
PD-0013: Real AstrBot transport mapping (OpenAPI/Dashboard vs /desktop/v1)
- Date noted: 2026-07-20
- Status: open; research complete; live container probe pending
- Source review:
docs/reports/astrbot-real-protocol-review.md - Finding: Local AstrBot clone
4.26.7exposes/api/v1developer OpenAPI (API Key + Dashboard JWT) and legacy/api/*routes. Chat streaming is request-scoped SSE fromPOST /api/v1/chat(plus optional run stream / WebSocket), not a long-lived Desktop Gateway event bus with ACK. - Missing on real server relative to provisional Desktop contract:
/desktop/v1/health|server-info|capabilities, access/refresh token pair, event ACK,tool.proposal, and/local-actions/*callbacks. - Safe interim rule: keep provisional Desktop protocol as the internal normalized model and Mock Gateway contract; implement a Rust
AstrBotAdapterfor real servers. Do not claim compatibility and do not rewrite the whole client. - Open items requiring live container probe: actual SSE type sequence, JWT expiry handling in practice, server-instance identity substitute, dual-profile isolation against one or two containers, and whether operations tooling remains Desktop-local for MVP.
- Stop boundary: if live probe proves only browser-cookie auth works, or requires AstrBot core changes for basic text chat, pause and escalate before coding the adapter.
- Interaction with existing open items: updates assumptions in PD-0009 and PD-0011; credential storage remains governed by PD-0010.
PD-0013 live probe update (2026-07-20)
- Live target
http://192.168.31.210:26285accepted API Key auth and streamed chat SSE fromPOST /api/v1/chat. - Dual usernames/session ids remained isolated on one server instance.
- Provisional
/desktop/v1remains non-native; adapter approach confirmed. - Chat MVP connectivity is unblocked. Server identity substitute, JWT login path, file/WS paths, and operations proposal source remain open.
PD-0014: Scheduled screen awareness scope and consent
- Date noted: 2026-07-27
- Status: direction selected; implementation remains blocked on the required full-desktop Spike and acceptance gates. Planning artifact: docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md.
- Decision update (2026-07-27): the product owner selected option B, the scoped full-desktop direction. This approves discovery and design only; it does not authorize capture code before the required Spike passes.
- Conflict: the requested product direction asks for randomly timed screen captures after a settings toggle, while ADR-0008 only permits a single user-authorized foreground window and requires a visible indicator, a stop control, Companion-only delivery, no on-disk raw frames, and Rust-owned policy enforcement.
- Proposed safe interpretation: “random” means random trigger time, not an unbounded random capture target. V1 may schedule captures only for a live, explicitly authorized foreground-window session. The interval is a hard minimum between successful captures and the configured probability is evaluated only after that interval has elapsed.
- Chosen scope direction: add a full-desktop capability after Spike approval. The eventual consent UI must require the user to select either one monitor or an explicit all-monitors scope; the scheduler is bound to that stable scope and may never choose a different monitor by itself.
- Mandatory gates before implementation: separate scope-specific consent, revised threat model, Windows.Graphics.Capture Spike results, lock-screen/full-screen/protected-content/sensitive-app handling, visible indicator and stop-path validation, Companion-only delivery, and real AstrBot visual acceptance.
- Non-negotiable exclusions: no hidden capture, browser-history collection, input logging, process injection, or automatic delivery to Operations.
- Safe interim rule: preserve the current capture policy unchanged until the full-desktop Spike has passed and the product owner accepts its evidence. C1–C3 page work may be planned independently; no scheduler, persistence migration, or capture-scope expansion is implemented in this planning phase.