docs(base44-troubleshooter): realtime logs --follow + a route to workflows runs - #157
Merged
Merged
Conversation
`--follow` is now a true realtime stream (sub-second) where the backend supports it, and falls back to polling (~20-30s ingestion lag) where it does not. The skill said none of this, and agents debugging live apps kept re-rolling flags against an index that simply had not caught up. - SKILL.md gets the load-bearing parts at the point of use: logs are not read-after-write, `--follow` first for live debugging, and the rule that the variable to change on an empty result is TIME, never a flag. Blind- agent runs showed reference-only guidance gets skipped entirely. - Fold in the consumer pitfalls hit for real during verification: never decide on a timer, per-invocation delivery, redeploy-safe streams, `--function` dropping unstamped legacy rows, `--since` rejected with `--follow`. - project-logs.md gets the long form: the two modes and the one-way fallback, how to read the SSE endpoint directly (pings prove liveness, the `end` frame's `retriable` flag is the whole contract, and a reconnect dedupes rather than replaying). - Correct two things the skill got wrong: there is no default page size (server caps at 500), and `--order` only orders the client-side multi-function merge — the server never reads it, so the old single-function `--order asc` example taught a no-op. - Spell out what an empty result actually means; it never means healthy.
davidsu
force-pushed
the
docs/troubleshooter-follow-realtime
branch
from
August 30, 2026 13:43
e5ee25a to
33f8218
Compare
…s runs An agent told "the nightly job stopped working" loaded this skill, found only `base44 logs`, and had no way to reach the command that answers it. Function logs cannot say whether a run was dispatched at all, which task failed, or why a workflow stopped firing. - Adds `workflows runs` and `workflows list` to the command table, linking the reference pages in the base44-cli skill (merged in #153). - New flow step, before the log-reading steps, on recognising that the failure was a scheduled run rather than a request. - Widens the skill description so it is loaded for automation and cron failures at all, not only for app errors. Calls out the two things that mislead: `manual` is the stamp on a run dispatched with no trigger type, not a human action, and test runs are included in the list, tagged as `(scheduled, test)`.
davidsu
changed the title
logs --follow [merge after cli#595 + release]logs --follow + a route to workflows runs [merge after cli#595 + release]
added 2 commits
August 31, 2026 13:57
… merged Verified against cli main at 50ad740 rather than against the branch head I first read (292b5fe). The squash carried a later commit that rewrote the fallback path, so two things in this PR had gone stale before it ever landed: - Both fallback warnings were reworded. The page quoted them verbatim, so it was byte-wrong against the shipped binary — the exact doc/impl mismatch that teaches agents to distrust the skill. - The mid-run fallback is gone. A stream that opened and later died used to drop to polling; it now throws "The realtime log stream stopped and could not be re-established". The page taught the opposite in two places. Rewritten around the real contract: the mode is decided once at startup, and a stream lost mid-run ends the command. Adds what that means for a script or agent loop — a non-zero exit partway through is the stream giving up, not a reason to change flags.
…-broad Both from cli-logs-realtime's review of e1863d0: - The raw-SSE section said a non-retriable end frame means fall back to the bounded polling route. True as advice to a third-party consumer, but the CLI itself exits on that frame — now stated, so a reader cannot generalise the advice back to the CLI. - The 500 cap was verified on the Cloudflare path only. On the legacy Deno path an omitted limit passes None through to the SDK, so "at most 500 whether or not you pass it" was unverified there. Now claims only what holds: no client default, and a passed value above 500 is clamped.
davidsu
marked this pull request as ready for review
August 31, 2026 11:00
davidsu
changed the title
logs --follow + a route to workflows runs [merge after cli#595 + release]logs --follow + a route to workflows runs
davidsu
added a commit
that referenced
this pull request
Aug 31, 2026
…#158) The raw-SSE aside said the CLI falls back to polling when the first connection is "refused", which is one of two causes. A first connect that keeps failing transiently exhausts its retries and polls too. The two-modes section above it already documents both, so the aside contradicted its own page. Caught in review of #157 after it merged. Co-authored-by: David Susskind <dev@example.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
base44 logs --followis now a true realtime stream (sub-second) where the backend supports it, falling back to polling (~20-30s ingestion lag) where it does not. The troubleshooter skill said none of this, so agents debugging live apps kept re-rolling flags against an index that had not caught up yet.Pairs with base44/cli#595.⚠️ Draft on purpose — this must land with or after the cli release, not before.
What changed
SKILL.mdgets the load-bearing parts at the point of use:--followfor live debugging, and the rule that on an empty result the variable to change is TIME, never a flag.--followpromoted to flow step 1, with the pitfalls that were hit for real during live verification: never decide on a timer, delivery is per-invocation, redeploying mid-follow is safe,--functiondrops unstamped legacy rows,--sinceis rejected with--follow.Placement follows the blind-agent finding in the CLI epic: one agent read only the reference and never a
SKILL.md, another read zero files and took flags from--help. Anything load-bearing goes inSKILL.md; the reference gets the long form.references/project-logs.mdgets the long form: the two modes and the one-way poll fallback, plus a raw-SSE section (pings prove liveness; theendframe'sretriableflag is the whole contract; a reconnect dedupes rather than replaying).Two things the skill got wrong
--limithas no default. The old "default: 50" was never applied; the server returns at most 500 either way and clamps a larger value.--orderis inert on a single function. The server never reads it — it only orders the client-side multi-function merge, so the oldlogs -n 100 --order ascexample taught a no-op. Replaced with a multi-function example.Verification
Every behavioral claim was checked against the CLI source on
feat/logs-follow-realtime-sserather than against existing docs — flag rejections atpackages/cli/src/cli/commands/project/logs.ts:419-434, the refusal→poll path atstream-api.ts:195-199→logs.ts:246-254, the one-way fallback atlogs.ts:261-285. Quoted CLI output strings match byte-for-byte (logs.ts:252-253,293,295). The--limitand--orderserver-side facts were verified against current apper code by the peer agent on that lane.