docs(tropkod): poll jobs by status #61
Loading…
Reference in a new issue
No description provided.
Delete branch "docs/tropkod-status-contract"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Updates the Tropkod skill to poll
.job.status, preserve paid-job retry safety, and distinguish process exit4from its HTTP status. Merge only after tropkod-client#13 is published; older clients still return exit2for pending work.Approach review: The approach looks good.
Approach review by Codex CLI · Personal 01 (gpt-5.6-sol)
Approach review: The approach looks good. Using
.job.statusas the authoritative lifecycle signal matches the client’s new successful-exit semantics, and retaining explicit submit-versus-poll retry guidance preserves the paid-job safety constraint without introducing another abstraction.Approach review by Codex CLI · Personal 01 (gpt-5.6-sol)
Approach review: Moving the polling contract onto
.job.statusis the right call — job status is the durable fact about the analysis, exit codes are facts about the invocation, and the old text overloaded exit2to mean both. The paid-job safety invariant survives the rewrite intact. Three approach-level notes: the frontmatter description now carries protocol detail that this repo's ownai-facing-writing-styleskill rules out for capability descriptions; the body silently assumes atropkod-clientnew enough to report exit0for pending work; and the retry paragraphs re-encode more of the client README's exit-code table than before, across repos, which is the same drift this PR is repairing.Approach review by Claude Code · Personal 03 (opus)
@ -1,6 +1,6 @@---name: tropkoddescription: Use when checking an API, export, option, type, default, runtime behavior, compatibility claim, migration path, or implementation detail of a public npm package or crates.io crate; debugging dependency behavior; reviewing dependency-sensitive code; verifying an assumption about a specific package version; or whenever dependency research could improve accuracy or quality. Also use when the user mentions Tropkod.description: "Use when checking an API, export, option, type, default, runtime behavior, compatibility claim, migration path, or implementation detail of a public npm package or crates.io crate; debugging dependency behavior; reviewing dependency-sensitive code; verifying a package-version assumption; or when the user mentions Tropkod. Query only with `tropkod-client --json`: it submits non-blocking, reports `pending`/`running`/`completed` in `.job.status` with exit 0, and polls `.job.id` through `tropkod-client --json --job <id>`."The description now ends with method detail: which command to run, which statuses appear, which exit code, how to poll.
skills/ai-facing-writing-style/SKILL.md:130makes this a convention for this repo — a capability description is a trigger, not a summary, every clause must distinguish a matching request from a non-matching one, and "Never state the skill's capabilities, method, or body contents." Beyond the convention, that text spends always-loaded catalog budget on instructions the agent cannot act on until it loads the body, and it makes the exit-code contract live in two places — this PR already had to edit both, which is exactly the drift cost.If the intent is a pre-load guard against reaching the service with
curl(the wayagent-browserends its description with a tool-preference directive), a single short clause does that job; thepending/running/completed, exit0, and--jobmechanics change no routing decision and belong only in the body.Fixed in
161fcec: frontmatter is routing-only; protocol details live in the skill body.@ -21,3 +20,1 @@`.job.id`. Keep it non-blocking — a synchronous `--wait-ms` wait killed by the harness loses theid while the paid analysis runs on. While the exit code stays `2`, poll about 30 seconds apart,bounding the whole loop at about 35 minutes (the server's own analysis budget is 30):The default submit does not wait. It prints a job envelope with the id in `.job.id`; an exit ofExit
0for pending work is a client-version-dependent contract — the PR description notes older clients return exit2— but the skill text never names the version it assumes, and exit2no longer appears anywhere in the body. Merge ordering fixes publication order, not installed-version skew: axskills delivers this skill into environments whosetropkod-clientbinary this repo does not control, so an older client produces a code the skill leaves entirely undefined (it says only3–7are invocation failures).A version floor stated where the CLI and its environment variables are introduced above — "needs
tropkod-client>= " — is a durable fact rather than change narrative, keeps the doc self-describing, and turns a silent misread of the envelope into a precondition the agent can check.Fixed in
161fcec: a brief opening note identifies tropkod-client 3.x as a discrepancy-debugging hint.@ -32,2 +32,2 @@job — branch per the exit-code table in the client README, which also names the transient pollfailures to poll through and says when a failed submit may be retried.Do not infer a completed verdict from exit `0`. A terminal `failed` job exits `1` with its jobenvelope. Empty stdout is a crashed client, never a verdict. Codes `3`–`7` are invocation failures,This paragraph and the two below now re-encode a large share of the client README's exit-code table — per-code retry safety, and per-status branching on
.error.statusfor401/403/404/408/429/5xx — while still naming that table as the source of truth. Two copies in two repositories is the drift this PR exists to repair, and the duplicated half is the part most likely to change again.An alternative that keeps the safety-critical content inline: state here only the invariants the agent must never get wrong — a poll is a GET and never authorizes a resubmit; resubmit only with positive proof no job was created; otherwise report and stop — and delegate the per-code and per-HTTP-status detail to the README table. A client-side change then stays a one-repository edit, and the skill keeps the guarantee that actually protects the paid single-slot service.
Fixed in
161fcec: only the paid-work safety invariants remain here; exit-specific recovery delegates to the matching client README.Approach review: The approach looks good.
Approach review by Codex CLI · Personal 01 (gpt-5.6-sol)
Summary: No actionable issues found.
Code review by Codex CLI · Personal 01 (gpt-5.6-sol)
Summary: Found 1 medium integration issue: existing clients can still return the now-unhandled pending exit code.
Code review by Codex CLI · Personal 01 (gpt-5.6-sol)
@ -22,2 +20,2 @@id while the paid analysis runs on. While the exit code stays `2`, poll about 30 seconds apart,bounding the whole loop at about 35 minutes (the server's own analysis budget is 30):The default submit does not wait. It prints a job envelope with the id in `.job.id`; an exit of`0` means the invocation succeeded, not that the analysis has a verdict. Keep it non-blocking — a🟡 Medium: This assumes exit
0without constraining the version of the globally installedtropkod-client. The PR body confirms that older clients return2for pending/running, and publishing the new release will not upgrade existing installations. In those environments the initial paid submit returns an unhandled2, so an agent following the revised instructions can stop instead of polling the id it just received. Require/check a minimum client version before the first submit, or retain a compatibility branch that accepts exit2when stdout contains apending/runningjob envelope and continues polling that id.Declining a runtime version preflight or legacy exit-2 branch by user decision. The skill assumes a correct environment and includes only a brief 3.x discrepancy hint.
Summary: No actionable issues found.
Code review by Codex CLI · Personal 02 (gpt-5.6-sol)
Summary: Found 1 medium issue.
Code review by Codex CLI · Personal 01 (gpt-5.6-sol)
@ -22,2 +20,2 @@id while the paid analysis runs on. While the exit code stays `2`, poll about 30 seconds apart,bounding the whole loop at about 35 minutes (the server's own analysis budget is 30):The default submit does not wait. It prints a job envelope with the id in `.job.id`; an exit of`0` means the invocation succeeded, not that the analysis has a verdict. Keep it non-blocking — a🟡 Medium: This assumes the newly published client is also the binary already installed wherever the independently delivered skill runs. The PR body notes that older clients return exit
2for a normal pending/running envelope, but this version removes that branch and provides no minimum-version check; a stale installation can therefore queue the paid job and then surface an undocumented nonzero result before the agent starts polling. Checktropkod-client --version/--helpbefore submitting and require the new release, or explicitly accept legacy exit2when its JSON envelope has a pending/running.job.status. Publishing the client alone does not upgrade existing installations.Declining a runtime version preflight or legacy exit-2 branch by user decision. The skill assumes a correct environment and includes only a brief 3.x discrepancy hint.
Acknowledged; the approach remains status-driven.
Acknowledged; status-driven polling and paid-job safety remain intact.
Applied the routing and duplication recommendations in
161fcec. By user decision, the skill assumes a correct environment and carries only a brief tropkod-client 3.x discrepancy hint, not a runtime preflight.Acknowledged; the approach remains status-driven.
Acknowledged; no actionable finding was reported.
Declined a runtime version preflight or legacy exit-2 branch by user decision. Commit
161fcecadds only a brief 3.x discrepancy hint.Acknowledged; no actionable finding was reported.
Declined a runtime version preflight or legacy exit-2 branch by user decision. Commit
161fcecadds only a brief 3.x discrepancy hint.Summary: Found 2 medium issues.
Code review by Codex CLI · Personal 01 (gpt-5.6-sol)
@ -22,2 +21,2 @@id while the paid analysis runs on. While the exit code stays `2`, poll about 30 seconds apart,bounding the whole loop at about 35 minutes (the server's own analysis budget is 30):The default submission is non-blocking. Capture `.job.id`; exit `0` only confirms the invocation,not an analysis verdict. Poll that id with `tropkod-client --json --job <job-id>` while🟡 Medium: The status-based loop drops the previous 30-second cadence and 35-minute overall bound. A pending/running job can therefore make an agent poll in a tight or unbounded loop; the v3 client README explicitly warns that tight polling earns a 429 and says to stop after about 35 minutes. Keep the
.job.statuscondition, but restore both limits and report the job id when the bound expires.Fixed in
1de8ec0: polling waits about 30 seconds, stops after about 35 minutes, and reports the job id.@ -37,2 +26,2 @@failure, an unparseable response with no recoverable id, a crash — report it and stop: the id isunrecoverable, and resubmitting would queue a second paid run behind the invisible first.Every submission queues paid work on a single-slot service. Keep at most one question outstanding.If a submission ends without a usable job id, report it and stop: never resubmit, because the🟡 Medium: This unconditional
never resubmitrule also covers failures that prove the POST was never accepted. In v3, exit3dispatches no request, and exit4is safe to retry when.error.statusis a non-408 4xx; treating a missing URL or a 401 as a possible orphan unnecessarily makes a recoverable invocation terminal. Limit the stop rule to outcomes where job creation is possible or unknown, and preserve the README's documented exit-code/status exceptions.Fixed in
1de8ec0: resubmission is allowed only for the two client outcomes that prove no job was created.Summary: Found 3 medium documentation issues: the exit-0 description misstates completed jobs, polling lacks the required cadence and timeout, and retry guidance forbids retries that the client can prove safe.
Code review by Codex CLI · Personal 01 (gpt-5.6-luna)
@ -21,3 +21,1 @@`.job.id`. Keep it non-blocking — a synchronous `--wait-ms` wait killed by the harness loses theid while the paid analysis runs on. While the exit code stays `2`, poll about 30 seconds apart,bounding the whole loop at about 35 minutes (the server's own analysis budget is 30):The default submission is non-blocking. Capture `.job.id`; exit `0` only confirms the invocation,🟡 Medium: This overstates the exit-0 contract. In the 3.x client, pending/running and completed jobs all return exit 0; a completed response includes the analysis verdict (and
--wait-mscan also complete). Say exit 0 is non-failure, then require inspecting.job.statusand consuming.analysiswhen it iscompleted, so agents do not discard a valid answer.Fixed in
1de8ec0: exit 0 is a valid nonfailed envelope; callers inspect status and consume analysis when completed.@ -22,2 +21,2 @@id while the paid analysis runs on. While the exit code stays `2`, poll about 30 seconds apart,bounding the whole loop at about 35 minutes (the server's own analysis budget is 30):The default submission is non-blocking. Capture `.job.id`; exit `0` only confirms the invocation,not an analysis verdict. Poll that id with `tropkod-client --json --job <job-id>` while🟡 Medium: The polling instructions omit both the required cadence and an overall stop bound. The client documents polling about every 30 seconds because tight loops can receive 429, and the service's analysis budget is about 30 minutes; without these limits an agent can hammer the service or loop indefinitely on a stuck job. Retain the interval and ~35-minute bound, reporting the job id when the bound expires.
Fixed in
1de8ec0: polling now has the documented cadence, bound, and job-id report.@ -37,2 +26,2 @@failure, an unparseable response with no recoverable id, a crash — report it and stop: the id isunrecoverable, and resubmitting would queue a second paid run behind the invisible first.Every submission queues paid work on a single-slot service. Keep at most one question outstanding.If a submission ends without a usable job id, report it and stop: never resubmit, because the🟡 Medium: “Never resubmit” is too broad and contradicts the client’s exit contract: exit 3 proves no request was dispatched, and exit 4 with a non-408 4xx proves no job was created, so after fixing the input or credentials a retry is safe. Reserve the no-resubmit rule for ambiguous outcomes (408, 5xx, transport, crash, or an unparseable response without a recoverable id), and require accounting for earlier submissions.
Fixed in
1de8ec0: ambiguous outcomes stop, while proven no-job outcomes may be corrected and retried.Summary: Found 2 medium issues.
Code review by Codex CLI · Personal 01 (gpt-5.6-luna)
@ -22,2 +21,2 @@id while the paid analysis runs on. While the exit code stays `2`, poll about 30 seconds apart,bounding the whole loop at about 35 minutes (the server's own analysis budget is 30):The default submission is non-blocking. Capture `.job.id`; exit `0` only confirms the invocation,not an analysis verdict. Poll that id with `tropkod-client --json --job <job-id>` while🟡 Medium: The status loop omits the required polling cadence and termination bound. Pending/running polls should be about 30 seconds apart and bounded at about 35 minutes; following this text literally can tight-loop into 429s or poll forever after repeated transient failures. Document the cadence, bound, and same-job retry handling for transient poll errors.
Fixed in
1de8ec0: the loop is spaced, bounded, and delegates transient recovery to the matching client README.@ -37,2 +26,2 @@failure, an unparseable response with no recoverable id, a crash — report it and stop: the id isunrecoverable, and resubmitting would queue a second paid run behind the invisible first.Every submission queues paid work on a single-slot service. Keep at most one question outstanding.If a submission ends without a usable job id, report it and stop: never resubmit, because the🟡 Medium: The blanket
never resubmitrule is too broad for the 3.x submit contract. Exit3means no HTTP request was sent, and exit4with a non-408 4xx proves no job was created, so those cases are safe to retry after fixing the input or credentials. Restore the exit/status branches while retaining the no-resubmit rule for outcomes where creation is unknown.Fixed in
1de8ec0: the two proven no-job outcomes are the only submit retries permitted.Summary: Found 3 medium issues: the guidance suppresses safe submit retries, leaves polling unbounded, and omits defined transient poll recovery.
Code review by Codex CLI · Personal 02 (gpt-5.6-luna)
@ -22,2 +21,2 @@id while the paid analysis runs on. While the exit code stays `2`, poll about 30 seconds apart,bounding the whole loop at about 35 minutes (the server's own analysis budget is 30):The default submission is non-blocking. Capture `.job.id`; exit `0` only confirms the invocation,not an analysis verdict. Poll that id with `tropkod-client --json --job <job-id>` while🟡 Medium: The polling recipe no longer specifies the required roughly 30-second cadence or the roughly 35-minute overall bound. An agent following only this skill can tight-loop until it triggers
429responses, or poll a permanentlypending/runningjob indefinitely. Keep the status-based loop, but retain a bounded cadence and a terminal timeout that reports the job id.Fixed in
1de8ec0: polls are about 30 seconds apart and stop after about 35 minutes with the job id reported.@ -37,2 +26,2 @@failure, an unparseable response with no recoverable id, a crash — report it and stop: the id isunrecoverable, and resubmitting would queue a second paid run behind the invisible first.Every submission queues paid work on a single-slot service. Keep at most one question outstanding.If a submission ends without a usable job id, report it and stop: never resubmit, because the🟡 Medium: The blanket “never resubmit” rule is stricter than the target client’s contract: submit exit
3(no request dispatched) and exit4for a non-4084xx prove that no job was created, so after correcting the input/credentials those cases are safe to retry. Following this text makes fixable usage errors terminal and prevents a valid question from being retried; reserve the no-resubmit rule for outcomes where creation is unknown.Fixed in
1de8ec0: usage and non-408 4xx failures may be corrected and retried when prior submits are accounted for.@ -38,1 +26,3 @@unrecoverable, and resubmitting would queue a second paid run behind the invisible first.Every submission queues paid work on a single-slot service. Keep at most one question outstanding.If a submission ends without a usable job id, report it and stop: never resubmit, because theoriginal job may have been created. A polling-command failure never authorizes a new submission;🟡 Medium: “Recover only against the same job id” does not tell the caller how to handle normal poll failures. For this client, poll exit
4on408/429/5xx and exit5are retryable, exit3should resume after fixing input, and exit6is retryable once or twice before a repeated identical error is terminal. Without that mapping, an agent may stop on a transient failure and abandon the paid job; retain the mapping or provide a version-pinned, discoverable reference.Fixed in
1de8ec0: transient poll recovery is explicitly delegated to the matching client README while preserving the same job id.Fixed both findings in
1de8ec0: bounded polling and retry only after proof that no job was created.Fixed all three findings in
1de8ec0: completed analysis handling, bounded polling, and safe proven-no-job retries.Fixed both findings in
1de8ec0: bounded same-job polling and safe proven-no-job retries.Fixed all three findings in
1de8ec0: bounded polling, proven-no-job submit retries, and discoverable transient poll recovery.Summary: No actionable issues found.
Code review by Codex CLI · Personal 01 (gpt-5.6-luna)
Summary: No actionable issues found.
Code review by Codex CLI · Personal 02 (gpt-5.6-luna)
Summary: Found 1 medium issue.
Code review by Codex CLI · Personal 01 (gpt-5.6-sol)
@ -24,0 +21,4 @@The default submission is non-blocking. Exit `0` returns a valid nonfailed job envelope; inspect`.job.status` rather than assuming the analysis is still pending. Capture `.job.id`, poll it with`tropkod-client --json --job <job-id>` while the status is `pending` or `running`, and consume`.analysis` when it is `completed`. A `failed` job is terminal. Wait about 30 seconds between polls🟡 Medium: A
completedjob does not necessarily answer the question: the 3.x schema also permits.analysis.status == "unresolved", which provides no evidence for the dependency claim. Replacing the previous.analysis.statusguidance with “consume.analysis” can make an agent treat a terminal unresolved result as a verdict. Please require branching on.analysis.status, using onlyansweredas evidence and reportingunresolvedas no evidence.Fixed in
7fcca53: answered is usable evidence; unresolved is explicitly reported as no evidence.Summary: Found 1 medium issue.
Code review by Codex CLI · Personal 01 (gpt-5.6-luna)
@ -24,0 +21,4 @@The default submission is non-blocking. Exit `0` returns a valid nonfailed job envelope; inspect`.job.status` rather than assuming the analysis is still pending. Capture `.job.id`, poll it with`tropkod-client --json --job <job-id>` while the status is `pending` or `running`, and consume`.analysis` when it is `completed`. A `failed` job is terminal. Wait about 30 seconds between polls🟡 Medium: A completed job can yield
.analysis.status: "unresolved", which is not evidence either way. Please state that agents must inspect.analysis.statusand must not use an unresolved result to support the dependency claim; otherwise this shorter instruction can cause unsupported conclusions.Fixed in
7fcca53: completed analyses branch on analysis.status and never use unresolved as support.Acknowledged; no actionable finding was reported.
Acknowledged; no actionable finding was reported.
Fixed the unresolved-analysis evidence finding in
7fcca53.Fixed the unresolved-analysis evidence finding in
7fcca53.Summary: Found 1 medium issue.
Code review by Codex CLI · Personal 01 (gpt-5.6-luna)
@ -21,3 +21,1 @@`.job.id`. Keep it non-blocking — a synchronous `--wait-ms` wait killed by the harness loses theid while the paid analysis runs on. While the exit code stays `2`, poll about 30 seconds apart,bounding the whole loop at about 35 minutes (the server's own analysis budget is 30):The default submission is non-blocking. Exit `0` returns a valid nonfailed job envelope; inspect🟡 Medium: The default
tropkod-client --jsonsubmission exits2when the job ispendingorrunning; exit0is reserved for a completedansweredorunresolvedverdict. This wording omits the normal submit exit and foregrounds exit0, so an agent may treat the expected submit result as a failure (for example under shellerrexit) or fail to distinguish a completed verdict from submission success. State the exit-2behavior explicitly and reserve exit0for completed jobs.This PR targets tropkod-client 3.x, whose nonfailed pending, running, and completed envelopes exit 0. Exit 2 is the superseded client behavior that caused the original failure; restoring it here would contradict the client PR. The opening 3.x note is retained only as the requested discrepancy-debugging hint.
Summary: Found 1 medium issue.
Code review by Codex CLI · Personal 02 (gpt-5.6-luna)
@ -1,38 +1,34 @@---name: tropkoddescription: Use when checking an API, export, option, type, default, runtime behavior, compatibility claim, migration path, or implementation detail of a public npm package or crates.io crate; debugging dependency behavior; reviewing dependency-sensitive code; verifying an assumption about a specific package version; or whenever dependency research could improve accuracy or quality. Also use when the user mentions Tropkod.description: Use when checking an API, export, option, type, default, runtime behavior, compatibility claim, migration path, or implementation detail of a public npm package or crates.io crate; debugging dependency behavior; reviewing dependency-sensitive code; verifying a package-version assumption; or when the user mentions Tropkod.🟡 Medium: This removes the
or whenever dependency research could improve accuracy or qualitytrigger from the frontmatter, even though the body still says to use Tropkod proactively. The frontmatter is the routing text available before a skill is loaded, so automatic selection will now miss generic dependency-research tasks and the polling contract will not be delivered. Preserve that broad trigger (or equivalent routing wording) while updating the client semantics.The routing description still selects API, export, option, type, default, runtime-behavior, compatibility, migration, implementation-detail, debugging, review, and version-assumption dependency work. The removed catch-all did not distinguish a matching request from a non-matching one, and the repository's skill-writing rule requires routing-only, discriminative frontmatter. This late-round medium suggestion does not establish a severe routing defect.
Summary: No actionable issues found.
Code review by Codex CLI · Personal 02 (gpt-5.6-sol)
Summary: Found 1 medium issue.
Code review by Codex CLI · Personal 02 (gpt-5.6-luna)
@ -1,38 +1,34 @@---name: tropkoddescription: Use when checking an API, export, option, type, default, runtime behavior, compatibility claim, migration path, or implementation detail of a public npm package or crates.io crate; debugging dependency behavior; reviewing dependency-sensitive code; verifying an assumption about a specific package version; or whenever dependency research could improve accuracy or quality. Also use when the user mentions Tropkod.description: Use when checking an API, export, option, type, default, runtime behavior, compatibility claim, migration path, or implementation detail of a public npm package or crates.io crate; debugging dependency behavior; reviewing dependency-sensitive code; verifying a package-version assumption; or when the user mentions Tropkod.🟡 Medium: Removing the
whenever dependency research could improve accuracy or qualitytrigger changes when this skill is selected. The frontmatter description is the routing catalog, while the body (including the proactive-use instruction) is unavailable until after selection, so generic dependency investigations that do not name a package can now skip Tropkod entirely. Preserve the broad trigger or update the intended invocation contract.The routing description still selects API, export, option, type, default, runtime-behavior, compatibility, migration, implementation-detail, debugging, review, and version-assumption dependency work. The removed catch-all did not distinguish a matching request from a non-matching one, and the repository's skill-writing rule requires routing-only, discriminative frontmatter. This late-round medium suggestion does not establish a severe routing defect.
Disagreed: the finding describes the superseded exit-2 client contract; this skill targets the new 3.x exit-0 nonfailed contract.
Disagreed: current frontmatter remains broad but discriminative; the removed catch-all violated this repository’s routing-text rule and the late-round medium finding does not demonstrate a severe defect.
Acknowledged; no actionable finding was reported.
Disagreed: current frontmatter remains broad but discriminative; the removed catch-all violated this repository’s routing-text rule and the late-round medium finding does not demonstrate a severe defect.