Repository navigation
docs(app-kit): state that hooks apps self-provision Python deps - #9774
Conversation
An app declaring only backend.hooks runs inside the Gateway process, so requirements.txt provisioning (backend-spawn path + stdio MCP registration) does not apply to it, and the provisioned tree is only reached by spawned children. The backend.hooks section said nothing about this. Add a Python-dependencies note stating the limitation as fact, with the .venv naming hazard (resolve_app_python prefers a probe-usable app venv for spawned work even when it holds nothing). Fixes #7879
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Design Review (Fable 5) — ✅ PASSDesign-level review of All claims verified against source. The diff is docs-only; every behavioral statement in the new prose matches the code (the two Design-Verdict: PASS Accurate, source-anchored documentation of a real capability boundary; docs-only is the right shape because the mechanism alternative is forbidden by the Gateway trust rule. [DESIGN-REVIEWED] 2ed6abb |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
bolichen97
left a comment
There was a problem hiding this comment.
Maintainer review (agent-assisted, on behalf of @bolichen97), head 2ed6abb0e.
Docs-only; both files accounted for. Every load-bearing claim in the new backend.hooks note holds against main: provision_app_deps has exactly two callers (apps/backend.py:1853, gated on a real file entry point, and bridges.py:2694), and start_app_backend returns early for hooks apps, so hooks apps do self-provision. Consistent with app-kit-platform.md.
Nit: manifest-reference.md:647 carries (see #7878 / #7901 for the mechanism) — a history reference in reader-facing docs; droppable.
…dotdev#9774) An app declaring only backend.hooks runs inside the Gateway process, so requirements.txt provisioning (backend-spawn path + stdio MCP registration) does not apply to it, and the provisioned tree is only reached by spawned children. The backend.hooks section said nothing about this. Add a Python-dependencies note stating the limitation as fact, with the .venv naming hazard (resolve_app_python prefers a probe-usable app venv for spawned work even when it holds nothing). Fixes kirodotdev#7879 Co-authored-by: Di Wu <dwu96@users.noreply.github.com>
Fixes #7879
Symptom
An app that declares only
backend.hooksgets norequirements.txtprovisioning, anddocs/app-kit/manifest-reference.md'sbackend.hookssection said nothing about Python dependencies — an author had no way to learn the limitation, the one mechanism that does serve hooks, or the.venvnaming trap.Root cause
Documentation gap. Hooks are imported into the Gateway process; runtime provisioning is deliberately reachable only from spawned surfaces, and front-placing an app-controlled tree on the Gateway's import path is forbidden by the trust rule in
_provision_app_deps_locked's docstring (src/kiro_crew/apps/backend.py:1264-1277) and the-m kiro_crew...carve-out (docs/app-kit/manifest-reference.md:57-59). Per the issue's own framing, a documented statement resolves it; the mechanism half is a platform design ruling and is out of scope here.Fix (documentation only — no behaviour change)
docs/app-kit/manifest-reference.md: a "Python dependencies" note at the end of thebackend.hookssection stating (1) runtime provisioning runs only on the backend-spawn and stdio-MCP paths, and hook code gets nothing from it; (2) the provisioned tree reaches spawned children via thedeps_bootshim /PYTHONPATHand is never on the Gateway's import path, with the shadowing rule made binding on hook authors; (3) the install-time build step is what serves hooks, with its real gates (registry installs only,package.jsonprecedence, pip failure fails the install, desktop bundled interpreter fails outright); (4) the.venvnaming hazard, scoped to the shapes that can actually trigger it.docs/app-kit/publishing-guide.md:492-494: the pre-existing "missing toolchain is a logged skip" sentence narrowed to npm — the pip step hard-fails — because the new note cross-references this flow and the sentence was wrong for pip (code docstring staleness tracked in Registry install: missing pip hard-fails the build despite docs and docstring claiming a soft skip #9770).Corrections to the issue as filed
data/.kirocrew-deps/(src/kiro_crew/apps/interpreter.py:54,73), beneathdata/soupdate_appkeeps the last good install — not the issue's hand-rolled<app>/.python-deps..venvpreference is probe-narrowed since fix: provision app requirements via pip --target, surface pip failures (#7878) #7901:resolve_app_python(interpreter.py:253-286) prefers<app>/.venvonly on positive evidence from an executed probe (_venv_is_usable,interpreter.py:151) and only when no provisioned tree is active. The surviving hazard — a runnable same-ABI venv holding no packages still displaces the gateway interpreter — is what the note documents.provision_app_depscallers (below). Companion issue Packaged install cannot provision an app's requirements.txt: bundled interpreter has no ensurepip, and the failure is not surfaced #7878 is closed as completed by fix: provision app requirements via pip --target, surface pip failures (#7878) #7901.Verification (every doc claim anchored to source at the verified SHA)
provision_app_depscallers: backend spawnsrc/kiro_crew/apps/backend.py:1842(gated on a real file entry point,backend.py:1831-1842) and stdio MCP registrationsrc/kiro_crew/apps/bridges.py:2694. Neither is the hooks path.start_app_backendearly-returns whenentryPointis unset:backend.py:764-765.src/kiro_crew/apps/hooks_integration.py: zero occurrences ofrequirements,deps_dir,app_deps, orsys.path.backend.py:2117-2177):deps_boot(site.addsitedir) for Python commands,PYTHONPATHonly on a positive ABI match;deps_boot.pyis a launch shim for spawned app processes only — the Gateway never adds an app deps tree to its ownsys.path.registry.py::_run_app_build(registry.py:6047-6184) runspip install ./-r requirements.txtonsys.executablein thesubdirectory-joinedapp_source(registry.py:5970);package.jsontakes precedence (if/elif,registry.py:6070/6085); npm-only soft skip (registry.py:6081-6084); nonzero pip fails the install (registry.py:6177-6184); desktop bundled interpreter fails outright (registry.py:6123-6132).origin/mainworktree (108 = 108 pre-existing environmental ids, identical invocationpytest -q -n auto --dist loadgroup). Frontend cross-surface guards: 230 files / 6,418 tests passed.check_comment_history.py,docs_lint.py,check_black_formatting.pyall pass; no narration phrases or non-inclusive terms in the diff.package.jsonprecedence,subdirectoryprecision,.venvhazard scoped to spawned surfaces. Declined with evidence: bare#NNNNrefs (precedent atdocs/app-kit/api-reference.md:210).No frontend change; the diff is documentation prose, so there is no visual delta a screenshot could evidence.
Pattern harvest
Rule candidate: when documenting a capability gap, anchor every sentence to a source line and enumerate the reachable states exhaustively — the review rounds here showed each unanchored generalization ("via PYTHONPATH", "a missing pip is a logged skip", "always the case for a hooks-only app") concealed a real behavioural fork (
if/elifprecedence, npm-vs-pip asymmetry, call-site gating) that would have misled the exact audience the note targets. Knowingly out-of-scope sibling: the stale soft-skip wording inregistry.py:6062-6066's docstring (#9770).