wangxuming/makelore
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
5d7a23598746a61f23f7b799b319a888d002d922
makelore/.project-docs/30-worklog/tasks/20260823-pi-core-host-api-a17f6c2e.md

11 KiB
Raw Blame History

Task: PI-100 Core Host API and Runtime Composition

Identity

  • Task ID: 20260823-pi-core-host-api-a17f6c2e
  • Mode: Feature
  • Branch: codex/20260823-pi-core-host-api-a17f6c2e-pi-core-host-api
  • Worktree: D:\Datas\OthersProjects\makelore-pi-core-host-api-a17f6c2e
  • Base commit: 98bac20639
  • Owner: codex-root
  • Status: Done

Scope

  • Implement PI-100's vendor-neutral project and Conversation service, core /api/coding routes, runtime Snapshot/Patch SSE, interactions, diagnostics, and HTTP 202 prompt acceptance contract.
  • Compose the production Pi runtime behind one Main-owned product Host composition, reusing PI-105's attachment store, product tools, change tracker, file routes, skills, and command projection.
  • Replace PI-105's temporary active-project adapter with the vendor-neutral project store and inject the target worker's live get_commands result.
  • Add focused route/service/composition tests and run the repository-required verification for Main/Renderer/packaging-impacting changes.

Intent And Constraints

  • Base is the reviewed cumulative PI-105 HEAD 98bac206396198cc276c659ed988372fc5c8bc10; PI-100 is the planner's exact sole Ready Frontier.
  • Project/partner/Conversation metadata creation must remain local-only and must not spawn Pi. Runtime preparation stays lazy at Snapshot or execution boundaries.
  • Routes validate active-project ownership and return stable, sanitized product errors. No Pi wire fields, absolute session paths, credentials, provider bodies, stderr, stacks, or extension paths may cross to Renderer.
  • Accepted prompt/steer/follow-up mutations return HTTP 202 without waiting for provider first token or settle. Accepted clientRequestId values are bounded and deduplicated; uncertain mutations are never silently resent.
  • The service is the deep product seam. Route files own HTTP parsing/projection, while process/RPC/event/session/provider lifecycle stays inside the existing Pi runtime modules.
  • Do not introduce an OpenCode fallback, runtime selector, compatibility adapter, second product-tool composition, or speculative security framework.
  • Real external Provider verification remains Explicitly Waived / Accepted Risk with realTurnVerified=false; macOS x64/arm64 remains deferred to the mandatory PI-150 gate. Neither is Pass evidence.
  • No subagents are authorized for this repository task.

Project Context Loaded

  • maintain-project-docs Concurrent Task Gate passed in the isolated worktree above; the canonical main worktree is occupied/dirty and was not modified.
  • Planning Gate inputs, canonical integrated memory, architecture/domain files, the only semantically adjacent active task, PI-105 completion record, and the planner's latest PI-100 ticket/Spec sections were read before planning.
  • The adjacent planning task 20260820-partner-create-model-parity-c83d has no defined scope or claimed files, so no ownership conflict is present.
  • Confirmed implementation seams: schema-v2 project/conversation stores, CodingConversationRuntime, PiConversationRuntime, managed extension host, PI-105's CodingProductComposition, and the shared Host dispatcher already exist. The temporary OpenCode project-store callback in Main is the seam PI-100 must remove from the product composition.
  • The canonical project-positioning and project-level success fields remain placeholders; ticket boundaries and product constraints therefore come from repository guidance, current-state memory, and the planner-owned normative Pi documents.
  • Gate result: Passed.

Plan

  1. Deepen the vendor-neutral project/Conversation service and runtime contract with the minimal Host-facing operations, bounded acceptance registry, event session, interaction correlation, command lookup, and safe diagnostics.
  2. Implement the project and Conversation route modules, including metadata CRUD, Snapshot, 202 mutations, SSE, interactions, and diagnostics with ownership validation and stable error projection.
  3. Build one production Main composition from the vendor-neutral project store, existing PI runtime/provider/resource/extension/product-tool seams, then register it in the shared Host dispatcher and shutdown lifecycle.
  4. Add focused service/route/composition regressions for local-only creation, dedupe/uncertain behavior, snapshot-first SSE, redaction, interaction IDs, project adapter replacement, and live command projection.
  5. Run focused tests, all Pi/coding tests, typecheck, lint, full unit suite, Vite build, Windows Electron coverage, documentation gates, and planner review; correct confirmed failures before completion.

Planner Review Correction

  • Planner review of 98bac20..22b4a9f concluded NEEDS FIX and kept the exact Ready Frontier at {PI-100}.
  • The correction scope is limited to eight confirmed contract gaps: unresolved model recovery, session trash on delete, protected uncertain-request tombstones, cleanup across every active-project transition, Renderer-safe project DTOs, production authentication recovery wiring, failed-fork runtime cleanup, and stable fixed Host error projection including storage failures.
  • PI-105 remains closed; its vendor-neutral project seam and live target get_commands seam were accepted structurally.
  • Planner re-review of cumulative HEAD 52b2467 again concluded NEEDS FIX and kept the Ready Frontier at {PI-100}. The three remaining P1 gaps were resolved/active Conversation model switching bypassing runtime.setModel(), credential-refresh rejection escaping the auth-required contract, and unmapped thinking/session-binding/runtime-model persistence failures.
  • The incremental correction keeps unresolved first-model selection on the validate/persist/initial-prepare path, restores target-only runtime model switching for resolved Conversations without disposal, types every production credential-refresh failure as authentication failure, and maps Pi session registry binding/model writes plus service thinking writes to the stable storage failure contract.
  • Planner incremental review of 52b2467...195979d concluded Standards PASS / Spec PASS / 0 findings. PI-100 was marked Done in the planner-owned Spec, ticket/DAG, and planner task record; the mechanically computed next Ready Frontier is exactly {PI-110}.

Outcome

  • Added the vendor-neutral CodingProjectService and CodingConversationService. Project/Agent/Conversation metadata creation is local-only; Snapshot and execution operations prepare the target worker lazily.
  • Implemented the Spec 12.1 core project/Conversation routes, global and target-filtered snapshot-first SSE, 202 prompt/steer/follow-up acceptance, bounded concurrent dedupe, uncertain-request retention, interaction correlation, and privacy-safe runtime diagnostics.
  • Extended the runtime product contract with safe commands, interactions, provider/resource invalidation, and diagnostics. Pi commands are fetched from the live target worker with get_commands; absent/unready workers degrade to the managed Makelore/skill catalog without exposing raw Pi fields.
  • Replaced PI-105's temporary OpenCode active-project callback with the product project service. Main now builds one shared product/Pi composition containing attachments, product tools, extension host, worker pool, subagents, project/Conversation services, and Host routes; the composition owns shutdown.
  • Provider changes advance the Pi provider revision, project config/knowledge changes advance the resource revision and invalidate cached Agent resources, and deactivating a project disposes its Conversation workers/interactions.
  • Resolved model changes reuse the target runtime's setModel operation and do not dispose an active worker; unresolved Conversations still persist the validated first model before lazy preparation. Provider refresh rejection is projected as CODING_PROVIDER_AUTH_REQUIRED, while authoritative Conversation/session write failures are projected as CODING_STORAGE_WRITE_FAILED.
  • No Renderer route was migrated here; PI-110 remains the next consumer of the new Main contract. Old /api/opencode removal remains PI-140 scope.

Verification

  • pnpm install --frozen-lockfile — Passed using the repository-pinned pnpm.
  • pnpm run typecheck — Passed after the latest review corrections.
  • pnpm run lint:check — Passed with zero errors; six existing Renderer warnings remain outside PI-100-owned files.
  • Latest review-focused suites — Passed: 4 files / 26 tests. Coverage adds resolved active-run target-only model switching without disposal, credential-refresh rejection and missing refreshed Works credentials, first session-binding write failure, runtime model metadata write failure, and service thinking metadata write failure.
  • pnpm test — Passed after the latest corrections: 209 files / 2263 tests passed, 2 skipped (2265 total).
  • pnpm run build:vite — Passed for Renderer, Electron Main, Preload, and utility worker. Existing dynamic-import/chunk-size warnings remain.
  • pnpm run test:e2e — Earlier cumulative PI-100 verification built the production app and passed 27/28 Windows Electron tests. The pre-existing OpenCode slash-command assertion failed because its legacy /command request omitted model; isolated rerun reproduced it. The latest correction changes only target model/auth/storage failure paths plus unit tests, so this legacy E2E was not rerun. No Renderer, OpenCode command route, or slash-command spec is changed by PI-100.
  • Real external Provider turns remain Explicitly Waived / Accepted Risk; realTurnVerified=false. This is not Pass evidence.
  • macOS x64/arm64 validation remains skipped by user direction and mandatory at PI-150. This is not Pass evidence.

Follow-ups

  • The exact next Ready Frontier is {PI-110}. It should bind the Renderer typed facade/store to these /api/coding routes and implement target Snapshot recovery on seq gaps.
  • PI-140 should remove the legacy OpenCode Renderer/routes/runtime residue after the hard cutover; PI-150 still owns final packaged platform qualification.
  • The legacy OpenCode slash-command E2E missing-model assertion should be reconciled by its owning UI/runtime task; it is outside PI-100 scope.

Promotion Candidates

  • Target canonical documents: current-state.md, system overview, module map, and PI ticket/DAG status.
  • Proposal: record PI-100 as implemented with the product project/Conversation services, core Host API, snapshot-first global SSE, one Main Pi composition, provider/resource revision integration, and PI-105 project/live-command seams closed.
  • Evidence: cumulative task commit(s), the focused Host/SSE tests, full unit result, typecheck/lint, and Vite build listed above.
  • Future impact: PI-110 may consume the new Main contract; PI-140 must still own legacy removal. The real Provider waiver and macOS deferral remain unchanged.
  • Semantic conflicts: none identified with accepted architecture or adjacent active task scopes. Human confirmation is not required for promotion, but the planner must review the cumulative HEAD before changing the Ready Frontier.