[RSPEED-2267] Convert service commands to return structured output

[subpop]

Refactor service-related tools to return structured data instead of plain text. This includes converting the output of list_services, get_service_status, and get_service_logs into JSON. Convert get_service_status to use systemctl show instead of the human-readably focused systemctl status. Implement a parser for the systemctl show command to facilitate this structured output.

[owtaylor]

I'm not quite sure how to to approach turning systemctl status into structured objects:

A) Parse the output, turn that into objects
B) Use lower-level API to obtain the information, reimplemen* the "summarization" of systemctl status inside our code.
C) Expose the low-level data sources, let the model parse through what it needs

A) is ugly and fragile. B) is ugly. C) will definitely lead to underperformance.

B) is probably best ,but considering how well trained models are on actual systemctl status output, I'm a bit skeptical about structured objects at all as applied to this tool. (It's also possible to have a tool return structured content and freeform content ... but I don't think that really helps things here.)

[subpop]

I'm not quite sure how to to approach turning systemctl status into structured objects:

A) Parse the output, turn that into objects B) Use lower-level API to obtain the information, reimplemen* the "summarization" of systemctl status inside our code. C) Expose the low-level data sources, let the model parse through what it needs

A) is ugly and fragile. B) is ugly. C) will definitely lead to underperformance.

B) is probably best ,but considering how well trained models are on actual systemctl status output, I'm a bit skeptical about structured objects at all as applied to this tool. (It's also possible to have a tool return structured content and freeform content ... but I don't think that really helps things here.)

Should we bother returning structured content for this tool then? Maybe the best thing for this tool in particular is to return the true expected output of systemctl status instead of trying to find some sort of structured content. There is no rule that says every tool must return structured content.

[owtaylor]

Should we bother returning structured content for this tool then? Maybe the best thing for this tool in particular is to return the true expected output of systemctl status instead of trying to find some sort of structured content. There is no rule that says every tool must return structured content.

@samdoran - what do you think?

[samdoran]

There are a couple of main things we want to accomplish:

• Remove the format_* functions since the whole notion behind them is flawed and better handled by a model.
• Validate the returned data and control the serialization of data returned from the tools when it makes sense.

These tools currently return nicely formatted text for display on a screen, but that text is never seen by a human. It may be helpful to send that formatted text to an LLM, but I doubt these specific formatting functions are swaying the accuracy of the LLM response and are therefore unnecessary.

One advantage of using Pydantic models for return types is that it provides validation of the returned data as well as control over how fields are serialized to JSON. For these particular tools, I don't think we need that capability since the output is mostly lines of text.

It may be the case that using Pydantic models for the return type, which is used to generate the return schema, may help the LLM make better use of the data that are returned, but I don't have a way to prove that.

For these tools, it's probably fine to just return the unaltered stdout.

[subpop]

I can see a pattern where it makes sense to return the unaltered stdout from a command, but that makes the most sense when the calling model has decided which command to run. Since our tools are abstracting the commands away from the model, we should be returning the most predictable data structure to a "list_services" function. So by that reasoning, I can see how we should convert these tools. Making up a data structure for the output of systemctl status doesn't fully make sense to me though. 🤔

[codecov]

Codecov Report

❌ Patch coverage is 98.57143% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/linux_mcp_server/tools/services.py	93.33%	1 Missing ⚠️

Flag	Coverage Δ
unittests	94.30% <98.57%> (-3.12%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/linux_mcp_server/commands.py	89.47% <ø> (+0.38%)	⬆️
src/linux_mcp_server/formatters.py	95.14% <ø> (-0.19%)	⬇️
tests/test_formatters.py	100.00% <ø> (ø)
tests/tools/test_services.py	100.00% <100.00%> (ø)
src/linux_mcp_server/tools/services.py	96.00% <93.33%> (+16.00%)	⬆️

... and 16 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[subpop]

Ok. I patched up the get_service_status tool to return the plain string output of systemctl status and updated the related tests. I think this is ready for review again, finally.

[github-actions]

For team members: test commit df69257 in internal GitLab

[github-actions]

For team members: test commit ad53afd in internal GitLab

[github-actions]

For team members: test commit d4b1d31 in internal GitLab

[owtaylor]

get_service_logs() and get_service_status() look good to me, but I have a bit of a hesititation about list_services.

[owtaylor]

So the arguments I know of for doing the structured data conversion are:

A) Not having to maintain fragile formatters. Accomplished, though we could just also pass through the data.
B) Accomodating models that want to "code mode" transform the data programatically. Not accomplished - what is in this list[dict[str, str]]? (Maybe the model would first write a script to extract a few sample lines, but it's annoying to make them do it.)

I think we should do:

class ServiceStatus(BaseModel):
    unit: str
    load: str
    active: str
    sub: str
    description: str

service_status_list_adapter = TypeAdapter(List[User])
...

return service_status_list_adapter.validate_json(stdout)

(systemd documents: "The list of possible LOAD, ACTIVE, and SUB states is not constant and new systemd releases may both add and remove values", so we probably shouldn't try use enums - a competent model will understand these mysterious load/active/sub values in terms of its systemd knowledge)