Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Make agentop and the installer depend only on documented contracts

Đang mở
  • Có gì không ổn?
#1,500 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
40/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
go, yaml
Lĩnh vực
backend, devtools, documentation

Hướng nghiên cứu

Start with cmd/agentop/local_endpoint.go and the listed agentop callers, then read docs/session-api.md, docs/README.md, the proxy handlers and scripts/install.sh. Add contract fixtures shared by agentop decoders and proxy handlers, and centralize the proxy process identity as the issue describes. Done means agentop no longer decodes config.Config, the endpoints and summary view are documented and checked for drift, and the process name is defined in one constant.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

enhancement laptop

Part of #1437 (assessment: laptop data plane on Praxis) · prep work, useful to Cortex on its own

Status: there is no Cortex–Praxis integration today, and the interim path is not decided (LLM traffic to praxis-ai as an inference server, or all traffic through Praxis via #1491). Nothing here depends on that choice: each item is useful to Cortex now, and makes an eventual move to Praxis easier whichever path is taken.

Problem

If the data plane ever changes, to Praxis or anything else, agentop and the installer should not notice. Today they depend on Go proxy internals beyond the documented session API:

  • the full Go config struct;
  • the reload and stats endpoints' exact JSON;
  • the proxy's binary name.

Any change to those internals, or a different proxy build, breaks agentop exec, server, pricing, doctor and service without warning.

What Cortex does today

agentop exec decodes /config into the whole Go config.Config (local_endpoint.go:289). It uses three fields: listener.forward_proxy_addr, tls_bridge.mode and tls_bridge.ca_dir (its own comment at :294).

13 agentop source files import core/config.

Stats endpoints agentop relies on have no documented contract:

view=summary is undocumented. agentop sends it on every timeline fetch (apiclient/snapshot.go:24), and docs/session-api.md doesn't mention it.

The proxy is recognised by binary name in two places:

The proxy's command-line contract (--version, --local --write-config, --local --supervise) is specified only by the test stub cortexStub.

Proposal

  1. agentop exec decodes only what it uses: a local three-field struct instead of config.Config.
  2. Document the stats contract. In docs/session-api.md or a new docs/stats-api.md: the JSON of /reload/status, /config (the fields agentop reads), /pricing/table and /tls-bridge/unread, plus view=summary. Add JSON fixtures that agentop's decoders and the proxy's handlers are both tested against.
  3. One constant for the proxy's process identity, used by isProxyComm, install.sh and uninstall. Write down the command-line contract the stub already encodes.
  4. Label each config section data plane or control plane in docs/README.md's config table, with its reload rule. That tells any future data-plane build which sections it must honour.
  5. Hot-reload as a stated contract. agentop edits ~/.cortex/config.yaml and waits on /reload/status (edit/local.go). Document that as the contract, rather than an implementation detail of core/reloader.

Design questions

  1. Should /config stay the source for exec, or should the session API expose the three values directly?
  2. Is the process-name check still needed once the service's own pid file or launchd label is authoritative?

Done when

  • agentop exec builds without decoding config.Config.
  • The four stats endpoints and view=summary are documented, with fixtures that fail on drift in either the proxy or agentop.
  • The proxy's process name appears in exactly one constant, plus install.sh, which references it in a comment.

Evidence read at main @ e455a04 (2026-10-25); not built or run.

Ngôn ngữ chính
Go
Star
18
Fork
42
Merge trung bình
12 giờ 20 phút
Pull request đã merge (30 ngày)
229

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của rossoctl/cortex

Tất cả issue của rossoctl/cortex

Issue tương tự

Thêm issue về Go

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.