Skip to content

TKM-169: Add plugin runtime logs and CLI reader - #259

Closed
JustKira wants to merge 10 commits into
feat/tkm-168-plugin-reloadfrom
feat/tkm-169-plugin-log
Closed

JustKira wants to merge 10 commits into
feat/tkm-168-plugin-reloadfrom
feat/tkm-169-plugin-log

Conversation

@JustKira

@JustKira JustKira commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #255.

Summary

Linear: TKM-169

server console, function result, or signed-in window report
  → bounded queue and one ordered file writer per plugin revision
  → <OS temp>/tokamak/logs/<installation key>/<id>.log
  → tokamak plugin logs <id> [--errors] [--json]

A broken log sink leaves invocations and workers running and emits one bounded diagnostic per failed writer. A 10 MiB cap or a backed-up queue produces one drop marker. A successful reload publishes the new revision's log, including initializer output; a failed reload leaves the previous log in place. The CLI streams records, counts malformed lines, and recognizes existing logs while the server is offline. Shared CLI changes add a streaming command result with stdout/stderr handling and reuse the plugin index reader; the command registry is unchanged by the review fixes.

Each JSON Lines entry contains time (Unix epoch milliseconds), source, level, kind, and text. Function entries distinguish exceptions, validation failures and cancellations; reload cancellations are informational. Worker errors include bounded, mapped stacks. The stopped screen shows the command and a copy button.

The host supplies the view owner and revision for render failures and callbacks it invokes (currently shortcuts). Unhandled browser errors and rejections outside those callbacks fall back to known module stack frames or the event filename. Without either, or when only a retired module URL is available, the host cannot attribute the error. The server rejects stale revisions and marks dropped window reports once per rate window (eight reports per plugin per ten seconds; up to 8,192 UTF-8 bytes per report).

Evidence

  • Before: An ordinary file in place of the log folder failed an embedded query and stopped a worker. An unchanged failing subscription wrote repeated errors. Reload erased initializer output and could overwrite another installation's log. A malformed record could stop the offline reader.
  • After: Real server regressions cover a failed sink and one diagnostic per plugin, 1,000 ordered full records, two concurrent producers, a reload while an action is active, preservation of loader output and other plugin logs, and rejected reloads. They also check malformed worker frames, UTF-8 truncation, mapped errors, subscription de-duplication, validation, stale window revisions, and rate markers.
  • Writer unit tests cover the byte cap and backlog marker. CLI regressions cover two installations, offline reading, read-through of malformed records, unknown ids, and filtering. Window tests cover attribution and copying the stopped-screen command; the Chromium browser test verifies delivery to the server.
  • A 32 MiB synthetic offline log streamed 8,037 records with zero skipped and about 107 MiB peak RSS on this machine (/usr/bin/time -l proto run bun -- packages/cli/src/main.ts plugin logs memory-fixture --json).
Local command Result
proto run bun -- test packages/cli/tests Passed: 19 tests.
cargo test -p server --no-fail-fast -- --test-threads=2 Passed in full: 168 tests passed, two real-adapter tests ignored by the suite.
cd app && proto run bun -- run test tests/plugins.test.tsx Passed: seven tests.
proto run bun -- run e2e:browser Passed: 20 Chromium and WebKit tests.
proto run bun -- e2e/run.ts Passed.
bash .ci/check.sh lint Passed: three tasks; TypeScript lint warnings remain.
bash .ci/check.sh ts Passed: type checks, tests, and web build.
bash .ci/check.sh rust Passed: 17 library tests.

Merge Danger

Door: Two-way. Logs are temporary. This changes the default log path, so logs written by a previous build at the old path are not found automatically.

Blast Radius: Plugins.

Any code running in the window can write an entry to any loaded plugin's log. This is accepted until plugin isolation exists.

@JustKira
JustKira marked this pull request as draft November 20, 2026 14:08
@JustKira
JustKira changed the base branch from feat/tkm-167-cli to feat/tkm-168-plugin-reload November 20, 2026 15:10
@JustKira

Copy link
Copy Markdown
Contributor Author

Closing without merging. The plugin shape, the server engine and sign-in are being decided again (Linear TKM-194 and TKM-195), and this work sits on top of them. Nothing is lost: the head commit is 94fa0f7, and git fetch origin pull/259/head brings it back.

@JustKira JustKira closed this Nov 21, 2026
@JustKira
JustKira deleted the feat/tkm-169-plugin-log branch November 21, 2026 18:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant