Skip to content

feat(plugin-sdk): re-export StatusSummary, SessionStatus, and HeartbeatStatus from command-status#77184

Open
lonexreb wants to merge 2 commits intoopenclaw:mainfrom
lonexreb:feat/76759-export-status-types
Open

feat(plugin-sdk): re-export StatusSummary, SessionStatus, and HeartbeatStatus from command-status#77184
lonexreb wants to merge 2 commits intoopenclaw:mainfrom
lonexreb:feat/76759-export-status-types

Conversation

@lonexreb
Copy link
Copy Markdown
Contributor

@lonexreb lonexreb commented May 4, 2026 •
edited
Loading

Summary

Adds three additive type re-exports to the existing openclaw/plugin-sdk/command-status entrypoint so plugins consuming gateway status RPCs (or formatting /status output) can bind against the canonical host shape:

  • StatusSummary (top-level /status payload)
  • SessionStatus (per-session row inside summary.sessions.recent[] / summary.sessions.byAgent[].recent[])
  • HeartbeatStatus (per-agent heartbeat status)

ModelCatalogEntry is already exposed via openclaw/plugin-sdk/agent-runtime (re-exported from agents/model-catalog.js) — kept as-is.

Why

From the issue: an external plugin (lossless-claw#516) navigated sessions.byAgent[].entries[].usage.{promptTokens, totalTokens, input} against StatusSummary — but the actual shape is sessions.byAgent[].recent[] keyed by key. The plugin's pickFirstNumber would have returned null on every field. Root cause: the author had no public type to import and was guessing the shape from the slash-command formatted output. Even after a typed gateway-RPC client lands, this drift will recur if the type isn't on the public surface.

Changes

  • src/plugin-sdk/command-status.ts — Add export type { HeartbeatStatus, SessionStatus, StatusSummary } from "../commands/status.types.js"; with a comment pointing at the issue.
  • src/plugin-sdk/command-status.types.test.ts — Regression test that imports each type and assigns from a sample literal so a future rename of the host type breaks here loudly.
  • CHANGELOG.md — Unreleased > Changes entry.
  • docs/.generated/plugin-sdk-api-baseline.sha256 — Regenerated via pnpm plugin-sdk:api:gen; pnpm plugin-sdk:api:check is green.

Per src/plugin-sdk/CLAUDE.md: additive, backwards-compatible, narrow. Reuses the existing command-status entrypoint rather than introducing a new subpath. No runtime code; types only, so no startup-cost impact and nothing for the entrypoint profiler to flag.

Test plan

  • pnpm test src/plugin-sdk/command-status.types.test.ts — 1/1 pass
  • pnpm plugin-sdk:api:gen — regenerated baseline
  • pnpm plugin-sdk:api:check — OK docs/.generated/plugin-sdk-api-baseline.sha256
  • pnpm exec oxfmt --check on touched files — clean

Refs #76759.

Real behavior proof

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation size: S labels May 4, 2026
@clawsweeper
Copy link
Copy Markdown
Contributor

clawsweeper Bot commented May 4, 2026 •
edited
Loading

Codex review: needs real behavior proof before merge.

Summary
The PR adds type-only re-exports for StatusSummary, SessionStatus, and HeartbeatStatus from openclaw/plugin-sdk/command-status, adds a type regression test, and updates SDK docs, changelog, and the API hash.

Reproducibility: not applicable. this is a public SDK API expansion rather than a runtime bug. Source inspection on current main confirms the canonical status types exist and the requested command-status subpath does not export them yet.

Real behavior proof
Needs real behavior proof before merge: The PR body has an empty Real behavior proof block, and the current head's proof check is failing.

Next step before merge
Contributor real behavior proof and maintainer SDK-contract acceptance are the remaining blockers; there is no narrow automated repair because the diff is already the proposed implementation.

Security
Cleared: Cleared: the diff is limited to type-only SDK exports, a type test, docs/changelog, and an API hash with no runtime, dependency, workflow, install, secret, or package-resolution change.

Review details

Best possible solution:

Land the additive export with docs, changelog, API hash, and focused type coverage once the contributor supplies real OpenClaw/plugin output showing the new import works and maintainers accept the public status payload contract.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a public SDK API expansion rather than a runtime bug. Source inspection on current main confirms the canonical status types exist and the requested command-status subpath does not export them yet.

Is this the best way to solve the issue?

Yes, conditionally: adding a type-only re-export to the existing command-status subpath is narrow and matches SDK guidance. Merge should wait for real setup proof and explicit maintainer acceptance of the new public status contract.

What I checked:

  • Current main missing requested exports: openclaw/plugin-sdk/command-status currently exports command/help builders and their option/result types, but not StatusSummary, SessionStatus, or HeartbeatStatus. (src/plugin-sdk/command-status.ts:1, 5fae1c32b5f8)
  • Canonical status types exist: SessionStatus, HeartbeatStatus, and StatusSummary are defined in the host status type module, with StatusSummary.sessions.byAgent[].recent[] using SessionStatus rows. (src/commands/status.types.ts:5, 5fae1c32b5f8)
  • Status summary current shape matches related report: Current main builds per-agent status rows under sessions.byAgent[].recent, supporting the related concern that plugins should not guess an entries[] shape. (src/commands/status.summary.ts:253, 5fae1c32b5f8)
  • Existing public SDK subpath: ./plugin-sdk/command-status is already a package export, so the PR expands an existing subpath rather than adding a new package entrypoint. (package.json:657, 5fae1c32b5f8)
  • SDK boundary guidance: The scoped SDK guide prefers narrow, additive, backwards-compatible subpaths and requires docs/API baseline/test alignment when expanding the boundary. (src/plugin-sdk/AGENTS.md:77, 5fae1c32b5f8)
  • PR diff adds type-only export: The PR adds an export type re-export for the three status payload types from the existing command-status SDK subpath, plus docs/changelog/API-hash/test updates. (src/plugin-sdk/command-status.ts:10, cfcfe6213ef7)

Likely related people:

  • Shakker: Current blame for the central command-status, status type, and SDK subpath docs lines points to the recent status/SDK formatting refactor. (role: recent maintainer; confidence: medium; commits: 3e53580d6311; files: src/plugin-sdk/command-status.ts, src/commands/status.types.ts, docs/plugins/sdk-subpaths.md)
  • steipete: Local history shows repeated recent plugin SDK API hash, package/export, release, and status-adjacent maintenance across the affected surface. (role: recent SDK/status maintainer; confidence: medium; commits: 4862d34925, 45586058e4, e6797bcd08; files: src/plugin-sdk/command-status.ts, docs/.generated/plugin-sdk-api-baseline.sha256, package.json)
  • hxy91819: The existing ClawSweeper discussion ties this person to the prior split of command status builders onto the plugin-sdk/command-status subpath that this PR expands. (role: adjacent SDK seam introducer; confidence: medium; commits: aa15de8fdc8b, ba636d120668; files: src/plugin-sdk/command-status.ts, src/plugin-sdk/command-auth.ts, docs/plugins/sdk-migration.md)

Remaining risk / open question:

  • The external PR currently fails the real behavior proof gate because the proof section is empty.
  • Publishing StatusSummary also makes host-owned nested status fields part of the practical SDK contract, so maintainers should explicitly accept that boundary.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 5fae1c32b5f8.

@lonexreb lonexreb force-pushed the feat/76759-export-status-types branch from 6c25e3a to 1e9ff48 Compare May 4, 2026 09:44
@lonexreb
Copy link
Copy Markdown
Contributor Author

lonexreb commented May 5, 2026

Fixed check-test-types failure: the test's StatusSummary["tasks"] literal didn't structurally overlap with the inner TaskRegistrySummary shape (active|terminal|failures|byStatus|byRuntime). Cast both tasks and taskAudit through unknown since the value of this test is type-portability of the OUTER StatusSummary re-export — host-internal nested types stay locked by their own tests in src/tasks/* and src/status/*.

@lonexreb lonexreb force-pushed the feat/76759-export-status-types branch 2 times, most recently from b1d7284 to ddc5e2b Compare May 5, 2026 05:33
@openclaw-barnacle openclaw-barnacle Bot added the triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. label May 5, 2026
lonexreb added 2 commits May 5, 2026 13:11
@lonexreb
feat(plugin-sdk): re-export StatusSummary, SessionStatus, and Heartbe…
7013dd3 
…atStatus from command-status (openclaw#76759)

Plugins that consume gateway status RPCs or format /status output had
no canonical type to import from openclaw/plugin-sdk and silently
drifted from the host shape (lossless-claw#516 audit hit the wrong
shape on every field). Re-export the three status payload types from
the existing command-status entrypoint so binding against the host
shape is one import instead of a copy-paste.

Additive only. ModelCatalogEntry already exposed via plugin-sdk/agent-runtime.

Tests: command-status.types.test.ts asserts the types are importable
and assignable from a sample StatusSummary literal.
API baseline regenerated (docs/.generated/plugin-sdk-api-baseline.sha256).
@lonexreb
fix(plugin-sdk): cast inner status fields through unknown in re-expor…
cfcfe62 
…t type test

CI check-test-types flagged an overlap mismatch on the StatusSummary['tasks']
shape — the inner TaskRegistrySummary requires { active, terminal, failures,
byStatus, byRuntime } and the test's { total, byScope } literal does not
overlap with that.

The point of this test is type-portability of the OUTER StatusSummary
re-export, not the host-internal nested types (which are locked by their own
tests in src/tasks/* and src/status/*). Cast through unknown for both
host-internal nested fields so the test asserts the public surface without
binding to host-internal shape.
@lonexreb lonexreb force-pushed the feat/76759-export-status-types branch from ddc5e2b to cfcfe62 Compare May 5, 2026 18:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to documentation size: S triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@lonexreb