feat(BA-6893): add kernel scheduling-history SDK v2 client and CLI commands

[jopemachine]

📚 Stacked PRs

• fix(BA-6887): reference the real from_status/to_status columns in kernel history conditions #12857 — BA-6887 fix: kernel history conditions reference the real status columns ✅
• feat(BA-6889): add kernel scheduling-history query conditions and orders #12867 — BA-6889 models: kernel query conditions and orders ✅
• feat(BA-6890): add kernel scheduling-history repository search scope #12868 — BA-6890 repository: kernel search scope and scoped search ✅
• feat(BA-6891): add kernel scheduling-history v2 DTOs and service actions #12869 — BA-6891 DTO + service: kernel v2 DTOs and search actions ✅
• feat(BA-6892): add kernel scheduling-history adapter and REST v2 endpoints #12870 — BA-6892 adapter + REST v2: kernel endpoints ✅
• feat(BA-6883): expose kernel scheduling history over GraphQL v2 #12989 — BA-6883 GraphQL v2: kernel history roots ✅
• fix(BA-6957): authorize kernel scoped scheduling-history via the owning session #13003 — BA-6957 fix: authorize kernel scoped history via the owning session ✅
• feat(BA-6893): add kernel scheduling-history SDK v2 client and CLI commands #12866 — BA-6893 SDK + CLI: kernel commands ← you are here
• test(BA-6953): add component tests for the kernel scheduling-history REST v2 endpoints #12997 — BA-6953 component tests: kernel REST v2 endpoints

Every PR below this one is merged, so this PR now branches straight off main and its diff is client-only.

Summary

SDK v2 methods and CLI commands over the two REST routes from #12870, completing the surface BA-6889..BA-6892 built up.

Command	SDK method	Route
bai scheduling-history kernel search	search_kernel_history(request)	POST /v2/scheduling-history/kernels/admin/search
bai scheduling-history kernel search-scoped KERNEL_ID	kernel_scoped_search(request)	POST /v2/scheduling-history/kernels/scoped/search

• Both commands sit in the user-facing cli/v2/scheduling_history/ group as a kernel sub-group, matching the existing session / deployment / route sub-groups of this entity. The system-wide search is still gated server-side by superadmin_required, so a regular user calling it gets a 403.
• Method naming follows the sibling sub-entities in the same SDK client (search_{entity}_history / {entity}_scoped_search), and the scope travels in the request body (ScopedSearchKernelHistoriesInput.scope) rather than as a path parameter.
• search-scoped takes the kernel id as a positional argument, like every other scoped search in the CLI, and wraps it into KernelHistoryScopeDTO(kernel=[UUIDScope(...)]) — the list-shaped scope introduced by feat(BA-6989): reshape KernelScope into scope-item lists and accept a session scope #13071 (BA-6989). --session-id on this command is an ordinary filter, not a second scope axis, because the server accepts exactly one scope item.
• The scoped search is authorized through the owning session (fix(BA-6957): authorize kernel scoped scheduling-history via the owning session #13003): whoever may read the session may read its kernels' scheduling history.
• This is the only PR in the stack with user-visible behaviour, so it carries the single news fragment. The layers below it are internal; a changelog entry on any of them would describe a change users never experience.

Not covered: #13071 also lets the scope name a session (scope.session), returning the history of every kernel that session owns. The CLI does not expose that axis — the positional argument is the kernel id. If it is wanted, it belongs in a follow-up as its own command rather than as an optional positional.

How to test

Common options for both commands: --limit / --offset, --phase (contains), --from-status / --to-status (repeatable), --result SUCCESS|FAILURE|STALE|NEED_RETRY|EXPIRED|GIVE_UP|SKIPPED, --error-code / --message (contains), --order-by created_at:desc (also updated_at, repeatable), --session-id. search additionally takes --kernel-id; on search-scoped the kernel id is the positional scope instead.

# Find a kernel id (admin)
bai admin session kernel search --limit 5

# 1. Owner reads their kernel's history → 200
bai scheduling-history kernel search-scoped <KERNEL_ID>

# 2. Filters and ordering
bai scheduling-history kernel search-scoped <KERNEL_ID> --result FAILURE
bai scheduling-history kernel search-scoped <KERNEL_ID> --order-by created_at:asc

# 3. System-wide search with filters (superadmin)
bai scheduling-history kernel search --session-id <SESSION_ID>

# 4. Permission gate: the system-wide search as a regular user → 403
bai scheduling-history kernel search --limit 1

# 5. Missing kernel → 404
bai scheduling-history kernel search-scoped 00000000-0000-0000-0000-000000000001

Note: kernel_scheduling_history has no writer yet (BA-6852), so an empty list is the expected live response. To see populated responses, insert rows directly; from_status / to_status must be valid KernelSchedulingPhase values (PREPARING|PULLING|PREPARED|CREATING|RUNNING|TERMINATING|TERMINATED) or serialization fails. Test accounts live in fixtures/manager/example-keypairs.json.

Test plan

Verified end to end against a live manager rebased onto current main (which includes #13071), with a seeded history row:

• search → 200; row fields (kernel_id, session_id, phase, from_status/to_status, result, attempts, timestamps) deserialize
• search-scoped KERNEL_ID → 200, returns only that kernel's rows
• search-scoped KERNEL_ID --session-id → matching session returns the row, non-matching returns none
• Filters (--phase, --result, --from-status, --to-status, --message, --kernel-id, --session-id) and --order-by created_at:desc
• --limit 1 --offset 1 → has_previous_page: true
• search-scoped with no positional → Missing argument 'KERNEL_ID'
• Missing kernel → 404 kernel_read_not-found
• Regular user calling search → 403; the same user's search-scoped on their own kernel → 200
• pants fmt / fix / lint / check clean
• Responses containing scheduler-written history rows — blocked on BA-6852 as above

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds kernel scheduling-history support to the SDK v2 and CLI.

Changes:

• Adds admin and scoped SDK requests.
• Adds kernel history filtering, ordering, and CLI commands.
• Updates changelog and CLI reference documentation.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
scheduling_history.py	Adds kernel-history SDK methods.
kernel.py	Implements kernel-history CLI commands.
commands.py	Registers the kernel subgroup.
12866.feature.md	Adds the user-facing changelog entry.
SKILL.md	Updates the CLI command reference.

Comments suppressed due to low confidence (1)

src/ai/backend/client/cli/v2/scheduling_history/kernel.py:183

• The scoped command uses the same seven-value KernelHistoryOrderField, but its help advertises only two fields. List all accepted fields so --help reflects the actual interface.

    help="Order by field:direction (e.g., created_at:desc). Fields: created_at, updated_at.",

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.