Skip to content

[agent] Add a read-only local Agent Core doctor #12

Description

@sam2tom

Context

Connection failures currently require operators to manually inspect a Core URL, proxy configuration, caller key files, daemon state, and provider setup. A safe local diagnostic command can make those layers visible without modifying Core state or sending a paid Turn.

Observable outcome: contributors can run one read-only command and receive a redacted, layered diagnosis instead of copying secrets or guessing from /healthz.

Acceptance criteria

  • Add pnpm core:doctor with an optional explicit Parsar checkout path.
  • Check the configured proxy target and conventional token-file path without printing token contents.
  • When local files are available, validate file presence/permissions and compare the caller token digest with the matching keys.json binding in memory only.
  • Check Core network liveness and authenticated basic Agents API reads without creating or changing any resource.
  • Detect non-sensitive daemon profile/process status when the upstream CLI exposes it.
  • Report separate states such as Core unreachable, Core API authenticated, daemon not observed, and provider not verified; never collapse them into a misleading Ready.
  • Treat execution/model readiness as Unknown unless a stable upstream contract proves it.
  • Redact tokens, authorization headers, URL query/fragment data, provider credentials, Session content, and private paths from shareable output.
  • Exit nonzero for actionable configuration failures and document the exit-code contract.
  • Add fixture-driven tests for missing files, unsafe permissions, digest mismatch, unreachable Core, 401, authenticated API, absent daemon, and redaction.

File ownership

  • new scripts/core-doctor.mjs
  • new scripts/core-doctor.test.mjs and scripts/fixtures/core-doctor/**
  • package.json only for the command/check entry

Do not edit connection UI, App.tsx, README files, or Agents client protocol types.

Validation

  • Run the doctor against fixtures and a deliberately unreachable loopback port.
  • Verify stdout/stderr, argv, fixtures, and snapshots contain no secret value.
  • Run pnpm check and git diff --check.
  • No database write, Session/Turn creation, or paid model request is allowed.

Non-goals

  • Do not generate or rotate credentials.
  • Do not run migrations or manage Core/daemon processes.
  • Do not claim provider readiness from process existence.
  • Do not implement Parsar Core behavior in this repository.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions