logs_panel_refresh.md

Logs Panel Refresh Design

Status

• Implemented in v6.3.0 as the first Logs Panel Refresh surface.
• Polished in v6.3.1 with shared LogView entry count display and stable identifiers.
• Initially documented in v5.6.0 as a planning-only design.
• Follows v6.0.0 App Shell / Sidebar Foundation.
• Follows v6.1.0 Profiles / Model List Surface.
• Follows v6.2.0 Detail Inspector Foundation.
• Dashboard UI Refresh v1 remains the current stable surface.

v6.3.0 adds a top-level Logs destination for app-managed lifecycle and log context. v6.3.1 keeps the same behavior and polishes the shared LogView with entry count display plus stable identifiers for the header, title, entry count, copy button, clear button, entry list, and empty state. It does not implement log filtering, log search, log export, log file persistence, external log capture, background log scraping, automatic diagnostics, background health checks, telemetry, metrics widgets, model download, model deletion, installed model scanning, cache cleanup, new persistence behavior, or runtime behavior changes.

Goals

• Make app-managed server logs easier to read.
• Clarify managed vs adopted external log boundaries.
• Keep lifecycle and ownership boundaries visible.
• Provide useful log context without adding background monitoring.
• Preserve Direct Mode.
• Preserve explicit lifecycle controls.
• Preserve external process ownership boundaries.
• Avoid capturing external logs.
• Avoid telemetry, diagnostics automation, and hidden background work.

Non-goals

• No external log capture.
• No background log scraping.
• No automatic diagnostics.
• No telemetry.
• No background health checks.
• No inference proxying.
• No Chat UI.
• No multi-backend routing.
• No hidden request rewriting.
• No model download.
• No model deletion.
• No installed model scanning.
• No cache management.
• No API key, token, or secret storage.
• No runtime behavior changes.
• No process ownership changes.
• No selected profile behavior changes.
• No current target behavior changes.
• No Import / Export behavior changes.
• No Import / Export schema changes.
• No /v1/chat/completions calls by the app.

Logs Surface Purpose

The future Logs surface should be a focused area for viewing app-managed server log output and lifecycle context.

It may show:

• managed server stdout/stderr log stream if already captured by the app,
• lifecycle events generated by app-managed actions,
• readiness check summaries if already available,
• current target context,
• ownership boundary notes,
• troubleshooting hints.

It must not become:

• an external process log collector,
• a telemetry system,
• a background monitoring agent,
• an automatic diagnostics runner,
• an inference proxy,
• a Chat UI.

Managed Server Logs

Future managed log content may include:

• managed server startup logs,
• managed server shutdown logs,
• readiness detection messages,
• launch command summary without secrets,
• error messages from app-owned process,
• copy-safe troubleshooting summary.

Clarify:

• logs come only from the app-managed process or app-owned lifecycle context,
• logs should not include secrets,
• logs should not imply request proxying,
• logs should not store tokens or API keys,
• log display should not require new background polling beyond explicitly designed app-owned behavior.

Adopted External Server Logs

Adopted external servers are connection context only. The app does not own the process.

The future Logs surface must clarify:

• MLX Server Manager does not capture external stdout/stderr,
• MLX Server Manager does not stop, restart, kill, or inspect external process logs,
• users should check the terminal, app, or service where the external server was launched,
• adopted external server logs are not available inside MLX Server Manager.

Future Logs surface may show:

• external target endpoint,
• readiness or detection summary already available to the app,
• ownership boundary explanation,
• "external logs are not captured here" message.

Candidate Logs Layout

These layout details are candidate design only, not implemented UI.

Header

• current target,
• managed vs adopted external badge,
• readiness state summary.

Managed Log Stream

• app-managed logs only,
• clear empty state,
• clear boundary when current target is adopted external.

Lifecycle Events

• explicit Start / Stop / Restart actions,
• detection and adoption notes,
• managed-process-only Stop / Restart reminder.

Troubleshooting Notes

• where to check external logs,
• Direct Mode reminder,
• no proxy reminder,
• readiness uses /v1/models only.

Copy Actions

• Copy logs summary.
• Copy endpoint summary.
• Copy troubleshooting context.

Copy Actions

Future copy affordances should be constrained and explicit.

Possible future copy actions:

• Copy visible managed logs.
• Copy troubleshooting summary.
• Copy endpoint or Base URL.
• Copy ownership summary.

Constraints:

• no generated secrets,
• no API keys,
• no token storage,
• no hidden request rewriting,
• no client-specific generated config unless separately designed,
• no copied text should imply the app proxies requests,
• no copied text should imply external process ownership,
• copied text should warn users to remove local paths or secrets before sharing logs.

Relationship to Dashboard v1

Dashboard v1 remains the high-level overview. It can continue to provide logs guidance and show short operational hints.

A future Logs surface can provide deeper managed-log context without turning Dashboard into a full log viewer. Dashboard should continue to answer "what should I do next?" while Logs answers "what happened in the app-managed server and lifecycle context?"

Relationship to Detail Inspector

The future Detail Inspector may show a compact current-target and log-boundary summary. The Logs surface provides the larger managed log view.

Adopted external boundary wording should be consistent across both surfaces:

• adopted external server is connection context only,
• external logs are not captured,
• external processes are not stopped, restarted, killed, or inspected.

See Detail Inspector Foundation Design for the future inspector boundary.

Relationship to Client Setup Surface

The future Logs surface may help troubleshoot managed server startup and readiness. A future Client Setup surface may link conceptually to logs guidance when users need to verify the active endpoint.

Adopted external server troubleshooting should point users to the terminal, app, or service where the external server was launched. Logs and Client Setup should both avoid implying external log capture, request proxying, generated credentials, or client configuration persistence.

See Client Setup Surface Design for the future Client Setup surface boundary.

Relationship to Metrics / System Context

The Logs surface provides app-managed log context. A future Metrics / System Context surface can provide system and readiness context.

Both surfaces should avoid external log capture, telemetry, background scraping, background monitoring, request logging, request tracing, and inference traffic inspection.

See Metrics / System Context Design for the future metrics and system context boundary.

Before any future v6 implementation begins, review v6 Implementation Readiness Review. Logs Panel Refresh remains a later candidate and should not be included in the initial App Shell / Sidebar Foundation implementation.

Relationship to Server / Current Target

The Logs surface can clarify managed vs adopted external target context. It can show lifecycle context without changing lifecycle behavior.

It must not:

• add new polling,
• add background health checks,
• change Start / Stop / Restart behavior,
• change External Server Detection / Adopt / Forget behavior,
• change process ownership semantics,
• take ownership of external processes.

Safety Boundaries

• Direct Mode remains unchanged.
• The app does not proxy inference requests.
• Lifecycle controls remain explicit.
• Stop and Restart apply only to app-managed processes.
• External servers remain connection context only.
• External logs are not captured.
• Import / Export remains metadata-only.
• No model download or deletion.
• No model scanning or cache cleanup.
• No API key, token, or secret persistence.
• No telemetry.
• No background automation.

Risks

• Users may expect external logs to appear.
• Users may think adopted external servers are app-owned.
• Log copy actions may leak local paths or secrets if not constrained.
• Log persistence may become a privacy issue if added later.
• Logs may imply inference request proxying if wording is unclear.
• Too much log detail may confuse non-CLI users.
• Automatic refresh wording may imply background monitoring if not constrained.

Acceptance Criteria for v6.3.0

The implementation is acceptable because:

• managed vs adopted external logs are clearly separated,
• external logs are not captured,
• Direct Mode is obvious,
• copied log or troubleshooting text contains no secrets,
• copied guidance does not imply proxying,
• lifecycle behavior is unchanged,
• no background monitoring is added,
• no telemetry is added,
• no API key, token, or secret persistence is added,
• Dashboard v1 remains stable,
• Start / Stop / Restart behavior is unchanged,
• Import / Export behavior is unchanged.

Future Stages

These versions remain proposals only:

• v6.0.0: App Shell / Sidebar Foundation.
• v6.1.0: Profiles / Model List Surface.
• v6.2.0: Detail Inspector Foundation.
• v6.3.0: Logs Panel Refresh.
• v6.4.0: Client Setup Surface.
• v6.5.0: Metrics / System Context Design.

v5.6.0 Planning Boundary

v5.6.0 added this detailed design only. v6.3.0 is the first app-code Logs Panel Refresh implementation. v6.3.1 is a focused Logs Surface polish release. Both keep the original safety boundaries intact.