Skip to content

Tracking Issue: local Server availability and service installation #1298

Closed

Description

@knqiufan

Status

RFC #1299 has been accepted and merged. This issue now tracks implementation of the accepted design. The merged RFC is the source of truth for the public contract, responsibility boundaries, security rules, and platform qualification requirements.

Implementation may be delivered through independently reviewed pull requests. A platform must continue to report unsupported until its adapter ships and passes the required base and native lifecycle tests on a matching runner.

Problem

powercontext server run is intentionally a foreground process. Agent integrations depend on a reachable Server and fail open when it is unavailable, so closing the terminal or restarting a personal machine can leave recall and capture unavailable during later agent sessions.

PowerContext needs a clear boundary among:

  • host-visible Server-unavailability diagnostics in agent integrations;
  • correlated installed-environment diagnostics in powercontext doctor;
  • opt-in native per-user service installation for personal use through a distribution/service-install layer;
  • container or administrator-managed services for managed deployments.

The Server role continues to own foreground process construction and powercontext server run. Integrations remain fail-open and do not install, start, or supervise the Server. Native service adapters belong to the distribution/service-install layer rather than src/powercontext/server.

Accepted design

  • RFC: docs(rfc): define local Server service-installation boundaries #1299

  • RFC state: accepted and merged

  • Personal lifecycle commands:

    powercontext service install
    powercontext service uninstall
    powercontext service status
    
  • The commands manage one opt-in service for the current operating-system user. There are no named profiles or privileged/system-wide installation modes.

  • The intended endpoint comes from local ServerSettings and must use a loopback bind. Client or integration server_url values do not select the local service registration.

  • service install performs endpoint preflight, installs or reconciles a verified PowerContext-owned native artifact, enables it for future logins, and starts it immediately unless a valid PowerContext Server is already live.

  • service uninstall stops a manager-owned process before removing the verified registration. It never kills a process only because it occupies the intended port.

  • service status reports independent support, registration, definition, manager, liveness, and log-location facts in human-readable and JSON forms.

  • Service artifacts contain no complete environment, API keys, bearer tokens, or provider credentials. File-backed settings and secrets remain a separate concern under the existing pydantic-settings direction and are not a general-availability condition for this work.

Tracking checklist

Design

  • Accept RFC docs(rfc): define local Server service-installation boundaries #1299
  • Fix the public lifecycle interface at powercontext service install|uninstall|status
  • Keep configuration and credential handoff separate from the service lifecycle contract
  • Define responsibility boundaries for the Server role, integrations, diagnostics, service-install layer, and managed deployments

Host-visible availability diagnostics

  • Surface a content-free server_unavailable outcome through each integration's host-appropriate visible channel while preserving fail-open behavior
  • Bound or deduplicate repeated Server-unavailable warnings
  • Keep authentication failure, version mismatch, invalid response, empty success, and Server unavailability distinct
  • Add per-host acceptance evidence for warning visibility and bounded repetition

Shared service state and doctor diagnostics

  • Implement the shared state model for support, registration, definition, manager, liveness, and log location
  • Extend powercontext doctor to correlate registration, native manager state, Server liveness, and Server readiness for the registered local endpoint
  • Keep unsupported and not_installed advisory when the optional service is not registered
  • Keep remote targets and nonmatching loopback targets independent of local service registration and manager state
  • Preserve equivalent human-readable and JSON diagnostic facts and safe recovery actions

Distribution/service-install layer

  • Add the top-level powercontext service command group only when the CLI and ready-to-run Server role are installed together
  • Implement the adapter protocol and distribution-owned internal launcher outside the Server role
  • Implement loopback and endpoint preflight, including valid PowerContext Server, address conflict, and unreachable outcomes
  • Implement idempotent install, atomic reconciliation, post-commit start-failure reporting, and executable-drift detection
  • Implement stop-before-remove uninstall and verified-ownership cleanup
  • Prevent privilege elevation, foreign-artifact overwrite, credential disclosure, and duplicate Server startup

Native per-user adapters

  • Linux: systemd --user, without /etc writes or enabling linger
  • macOS: current-user LaunchAgent with explicit per-user stdout and stderr paths
  • Windows: current-user Task Scheduler logon task with explicit per-user Server logs
  • Fix and test project-owned native identifiers, ownership markers, definition versions, and bounded restart policies

Documentation and validation

  • Document interactive personal, persistent personal, and managed deployment profiles
  • Document install, status, uninstall, reconciliation after upgrades, recovery actions, and log locations
  • Add focused tests for rendering, ownership, loopback validation, reconciliation, rollback, launcher preflight, status semantics, and redaction
  • Add native register, query, start, stop, and remove tests on matching operating-system runners
  • Keep release documentation and service status honest about actual platform availability
  • Require the base install and Server smoke tests before advertising Windows adapter support

Delivery

Implementation may be split into separate pull requests for:

  1. host-visible integration diagnostics;
  2. correlated doctor diagnostics and the shared service state model;
  3. the distribution-owned CLI, internal launcher, and adapter protocol;
  4. Linux, macOS, and Windows adapters;
  5. documentation and platform integration tests.

Link accepted implementation pull requests to this issue and update the checklist as they land. Each pull request should preserve the accepted RFC contract and include the tests and documentation needed for the behavior it advertises.

Out of scope

  • Starting or installing the Server from an agent hook
  • Enabling persistent service installation during setup
  • Installing a machine-wide, root, SYSTEM, or administrator service
  • Public binding, remote multi-user service profiles, or managed-deployment automation
  • A PowerContext-specific supervisor
  • A portable secret store or environment snapshot

Activity

  1. PsiACE commented on Aug 21, 2026

    @PsiACE
    Member

    @knqiufan Thanks for the proposal. I think autostart belongs in a distribution/service-install layer rather than the Server CLI. First, plugins should surface Server unavailability, with doctor providing a clear diagnostic. Personal installs can use native user services through the distribution layer, while managed deployments should use containers or administrator-managed system services. Let’s scope the issue around this boundary before implementation.

  2. PsiACE commented on Aug 21, 2026

    @PsiACE
    Member

    This is a good fit for an RFC so we can discuss and agree on the design. Once accepted, a tracking issue can track progress and split the implementation.

  3. knqiufan commented on Aug 21, 2026

    @knqiufan
    CollaboratorAuthor

    @PsiACE Thanks for clarifying the boundary and process. That makes sense. I will open a docs-only RFC to discuss and agree on the responsibility split among plugin-visible Server availability, doctor diagnostics, the distribution/service-install layer for personal installs, and container or administrator-managed services for managed deployments before any implementation. I will link the RFC PR here once it is open.

  4. changed the title [-]feat: add opt-in login autostart for the local Server[/-] [+]tracking: local Server availability and service installation[/+] on Aug 21, 2026
  5. knqiufan commented on Aug 21, 2026

    @knqiufan
    CollaboratorAuthor

    RFC opened for design discussion: #1299. I have updated this issue to track RFC acceptance and the subsequent diagnostic, distribution/service-install, and native-adapter work. Implementation remains blocked until the RFC is accepted.

  6. changed the title [-]tracking: local Server availability and service installation[/-] [+]Tracking Issue: local Server availability and service installation[/+] on Aug 21, 2026
  7. knqiufan commented on Aug 23, 2026

    @knqiufan
    CollaboratorAuthor

    @PsiACE RFC #1299 has now been accepted and merged. I updated this tracking issue to reflect the accepted command contract, responsibility boundaries, delivery split, platform qualification, and validation requirements.

    I would like to continue with the implementation. To keep review and rollback bounded, I propose the following sequence:

    1. Add the shared service state model, the distribution-owned powercontext service CLI and adapter protocol, and the internal launcher preflight.
    2. Add correlated powercontext doctor diagnostics after the current stacked CLI work in feat(cli): add setup select for explicit multi-host plugin install #1311 and feat(cli): add doctor integrations for first-class host status #1314 land, so the service checks build on the settled doctor surface.
    3. Deliver the native adapters as independently reviewed changes: Linux systemd --user, macOS LaunchAgent, and Windows Task Scheduler. Each platform will remain unsupported until its native lifecycle tests and required base smoke tests pass on a matching runner.
    4. Add host-visible, content-free, bounded server_unavailable diagnostics for each supported integration while preserving fail-open behavior and distinct failure outcomes.
    5. Include the documentation and platform acceptance evidence with the implementation slice that advertises each behavior.

    Could you please confirm whether this split and order match the intended project priority?

  8. Alanxtl commented on Aug 24, 2026

    @Alanxtl
    Collaborator

    /assign, claimed in weekly meeting

  9. AlexStocks commented on Aug 24, 2026

    @AlexStocks
    Contributor

    /assign, claimed in weekly meeting

    done

  10. Alanxtl commented on Aug 24, 2026

    @Alanxtl
    Collaborator

    @knqiufan @PsiACE hi, Thanks for the accepted RFC. I plan to implement #1298 as a sequence 5-7 PRs.

    Proposed implementation order:

    1. Surface content-free server_unavailable diagnostics in each supported integration while preserving fail-open behavior.

      To make sure the using agent can see the unavailable cause.

    2. Extend powercontext doctor with service support, registration, definition, native manager, Server liveness, and readiness checks.

      including service_support | service_registration | service_definition | service_manager | server_liveness | server_readiness

    3. Add the shared personal-service state model, ownership checks, launcher contract, and the public commands:

    • powercontext service install
    • powercontext service status
    • powercontext service uninstall
    1. Implement native per-user adapters separately:
      • Linux: systemd --user
      • macOS: per-user LaunchAgent
      • Windows: per-user Task Scheduler logon task
    2. Add documentation, platform-specific lifecycle tests, security tests, and CI coverage on matching runners.

    If this plan is ok, I'll summit pr asap

  11. knqiufan commented on Aug 24, 2026

    @knqiufan
    CollaboratorAuthor

    @Alanxtl Thanks for taking this on, the proposed direction looks good, but I suggest a few adjustments to the dependency order and PR boundaries before implementation:

    1. The shared service state model, adapter protocol, launcher preflight, ownership rules, and lifecycle orchestration should land before the correlated doctor checks. Doctor should consume the shared service facts rather than introduce a separate native-state implementation.
    2. Host-visible server_unavailable diagnostics can proceed first or in parallel with the service work. Please define the exact integration scope—at least codex, claude-code, dsh, openclaw, pi, and hermes—and clarify whether Bub is out of scope. The diagnostic should be visible to the user through the host’s supported channel, remain content-free and fail-open, preserve distinct failure outcomes, point to powercontext doctor, and use bounded or deduplicated presentation.
    3. Keeping Linux, macOS, and Windows adapters in separate PRs. Each platform PR should include its native lifecycle tests, ownership and restart-policy coverage, matching-runner CI, documentation, and support qualification. The platform must continue reporting unsupported until that evidence passes; Windows additionally needs the required base install and Server smoke tests.
    4. Documentation, security tests, lifecycle tests, and CI coverage should accompany the implementation slice that advertises the behavior rather than being deferred to one final PR. A final documentation PR can consolidate deployment guidance, but it should not be required to qualify behavior merged earlier.

    I suggest dependency-safe sequence would therefore be:

    1. Host-visible integration diagnostics, split into one or two reviewable PRs if needed.
    2. Shared service core and public lifecycle CLI.
    3. Correlated doctor diagnostics.
    4. Linux adapter.
    5. macOS adapter.
    6. Windows adapter.

    If the shared service core becomes too large, separating the state/protocol/launcher foundation from the public lifecycle orchestration would also be reasonable, even if that takes the total slightly beyond the planned PRs.

  12. Alanxtl commented on Aug 26, 2026

    @Alanxtl
    Collaborator
  13. moved this from Todo to In progress in PowerContexton Aug 26, 2026
  14. moved this from In progress to Done in PowerContexton Sep 2, 2026
  15. Alanxtl commented on Sep 2, 2026

    @Alanxtl
    Collaborator

    pls do not close it now, there are still remaining works

  16. reopened this on Sep 2, 2026
  17. moved this from Done to In progress in PowerContexton Sep 3, 2026
  18. moved this from In progress to Done in PowerContexton Sep 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions