docs(mcp): no migration command -- record the decision and the recipe (#390) - #581
Merged
Conversation
…#390) Decision: `kbagent agent migrate-mcp-tasks` will not be built. Migrating a scheduled `--type mcp_tool` task before v0.85.0 is manual, or AI-assisted. The reasoning that killed automatic rewriting also argues against a plan-generator: the parity map knows which native command replaces each tool but not how to map arguments -- mcp_tool params are the MCP tool's own `input` dict (`componentId`) against CLI flags (`--component-id`), with different shapes for several tools. An agent reading `--help` next to the task's actual input does that mapping better than any generator we could ship, and has a human confirming. Detection already landed in #557, which is the part that could not be improvised: `doctor` names every affected task and its native_command, and `agent list` / serve `/agents` carry a deprecation key. So this is documentation, not tooling: - gotchas.md states plainly that no command exists and why, then gives the four-step recipe (doctor for the ids, agents.json for the input, --help for the flags, agent update + one agent run before trusting the cron). - keboola-expert.md gets a one-line trigger pointing at it, kept short on purpose: that file is at 61.6 KB of its 62 KB budget. Note the residual risk, since it is a judgement and not a measurement: we have no telemetry, so "probably nobody uses this" is a call about the user base, not an observation. If it is wrong the failure mode is a silently dead cron task -- but `kbagent doctor` now surfaces exactly that, which is why the decision is defensible without the command.
15 tasks
Devin review of #581, and it landed on the point of the PR: step 4 told the reader to run `kbagent agent update <id> --type cli_command --argv ...`. That command patches name/cron/enabled/trigger only and explicitly cannot change a task's action, so the documented path exited 2. In a PR whose whole premise is "a recipe instead of tooling", a recipe that fails at its last step is worse than none. Corrected to what works today: `agent create` the replacement, verify it with one `agent run`, then `agent delete` the old task. That path has a trap Devin's suggestion did not mention, so it is now spelled out: `Trigger.task_id` chains tasks BY ID, and create-new + delete-old changes the id. Any other task pointing at the old one via --trigger-task-id must be repointed FIRST or the chain breaks silently. tests/test_mcp_migration_recipe.py pins the recipe to the CLI's real flags, including an anchor asserting `agent update` still cannot change the action -- if that ever gains --type/--argv, the test fails and the docs get simpler.
The guard I added against a broken recipe was itself broken: _options_of() scraped `--help` to decide which flags a command has. Rendered help is a presentation concern -- Rich wraps and truncates it by terminal width and TTY detection -- so an option can be present in the interface and absent from the text. It passed locally (including at COLUMNS=80) and failed on all three CI runners. Rather than chase what differs about the CI environment, the helper now reads `params` off the command object, where the contract actually lives. Width and TTY stop mattering. Walking the tree is duck-typed on a `commands` dict rather than isinstance(click.Group): Typer builds its own Command/Group subclasses, so the click check is False at runtime -- which broke the first attempt at this fix.
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.
Decision:
kbagent agent migrate-mcp-taskswill not be built. Migrating ascheduled
--type mcp_tooltask before v0.85.0 is manual, or AI-assisted.The reasoning that killed automatic rewriting also argues against a
plan-generator: the parity map knows which native command replaces each tool
but not how to map arguments -- mcp_tool params are the MCP tool's own
inputdict (
componentId) against CLI flags (--component-id), with differentshapes for several tools. An agent reading
--helpnext to the task's actualinput does that mapping better than any generator we could ship, and has a
human confirming. Detection already landed in #557, which is the part that
could not be improvised:
doctornames every affected task and itsnative_command, and
agent list/ serve/agentscarry a deprecation key.So this is documentation, not tooling:
four-step recipe (doctor for the ids, agents.json for the input, --help for
the flags, agent update + one agent run before trusting the cron).
purpose: that file is at 61.6 KB of its 62 KB budget.
Note the residual risk, since it is a judgement and not a measurement: we have
no telemetry, so "probably nobody uses this" is a call about the user base, not
an observation. If it is wrong the failure mode is a silently dead cron task --
but
kbagent doctornow surfaces exactly that, which is why the decision isdefensible without the command.