Repository navigation
feat(app-kit): publish a backend SDK for an app's own python - #36341
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the change only adds a package, and each name delegates at call time to the control the gateway itself enforces, so the public surface cannot drift from those controls. Notes
[DESIGN-REVIEWED] 2706d63 Description read[DESCRIPTION-READ] bc9214f58ff1731db33ff86d1b6df30a2b386cdcdaf264014683e99d3208d51a That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Every item is an app-agnostic App Kit seam, which the AGENTS.md "No built-in apps" rule requires as the fix for a capability gap. Every delegate calls the gateway's own control at call time, and no default changes for anyone who doesn't import it. Not checked: the per-group app counts (7/7/7/6/4/4/3) come from external app repositories, which I couldn't read. What this change shipsInventory (8 items) — 8 justifiedIntent: let a former built-in's backend call the gateway's own security, sandbox and process controls through a public, stable name instead of private
[FIRST-PRINCIPLES-REVIEWED] 2706d63 Description read[DESCRIPTION-READ] 96ad05a558942d4e7907a23f712aa35e38fe419a9c47e112a233a2744d1fad22 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 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: |
e527733 to
ebc0c2a
Compare
|
self-added: no
(This GPT verdict for e527733 was produced but never published: the installation token hit GitHub's rate limit while the lane posted it.) |
|
self-added: no
(This GPT verdict for e527733 was produced but never published: the installation token hit GitHub's rate limit while the lane posted it.) |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 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: |
ebc0c2a to
78b4ca7
Compare
|
self-added: yes
|
78b4ca7 to
cc6f5f8
Compare
|
Rebased: main moved in docs/app-kit/api-reference.md, docs/system-specs/modules/app-kit-platform.md, scripts/adoption_pin.py since this head went green (ff344c7 -> 00c5418); CI re-running. The conflict was #33589 landing level 7 first: per the #26967 seam-level decision this PR keeps 7, adds the backend SDK to the level-7 list, and its spec section moves to §40 (§39 is now agent-read-only directories). |
Code change approver recommendation: A person should decideWhy: the decider raised 1 possible problem and estimates a 55% chance that this change introduces a defect; a person should check it. This PR adds a public package of thin delegates, kiro_crew.apps.backend_sdk, for app backends: sensitive-path checks, a no-follow read, atomic write, redaction, an audit writer, sandboxed spawn and process helpers. It also counts the package as a level-7 seam in the adoption pin tool. The code looks correct. Every delegate exists on its facade with a compatible signature, and the spawn seam narrows reach: only the standard and strict tiers are accepted, and only listed run keywords. The scrubbed environment and launcher cleanup hold on every path, the async form kills the child's process group, and the spawn-audit tokens are satisfied. Nothing existing changes. But the blocking Backend Lint & Type Check job failed on this head, so the Coverage Gate failed closed and every backend test suite was skipped. The new security-relevant seam and its real-child tests have not run in CI, and PR Readiness is still pending. A careful maintainer would not merge until lint is fixed and the test matrix passes. Things to check (possible problems the decider raised; at this confidence many turn out to be fine):
An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
Add kiro_crew.apps.backend_sdk, the public, documented spelling of the private host names the app repositories reach most through their _host.py shims: sensitive-path checks, the no-follow read, atomic write and owner-only dirs, outbound redaction, the audit writer, the sandboxed spawn chokepoint and the platform_compat process and lock helpers. Each name delegates at call time to the control the gateway enforces, raises the gateway's own exception classes, and offers no knob that widens the sandbox. It imports the same way in a hooks backend and in a spawned backend on the gateway interpreter. The package is App Kit seam level 7; the adoption pin tool counts a tree that names it as a level-7 use. Part of #26967
cc6f5f8 to
2706d63
Compare
|
Green-age note for 2706d63: |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
This review checked head 2706d63. Every SDK name delegates at call time to the gateway's own control, and the delegate signatures and re-exported exception classes match their targets. The spawn seam only narrows: it accepts only the standard and strict tiers, refuses before preparing, and forwards an allowlist of run keywords. The async form reads the process group while the child is alive and kills it on both timeout and cancel. The tests wait on signals with bounded timeouts, and the adoption pin only gains cases.
Done well: a real sh -c child that leaves a sleep 600 behind pins the case where the descendant outlives a reaped leader.
Optional:
- Inside a spawned backend, which already runs at standard,
mode="strict"passes through at the outer standard tier and only scrubs the environment. With the operator'ssandbox_allow_unsandboxed_execopt-in, the child runs unconfined. The spawn.py docstring, the api-reference row and spec section 40 could say so. - No test covers the tier check or the scrubbed
env=inrun_sandboxed_async. Removing either one leaves the suite green. A test that the async form refusesmode="off", plus a test that records theenvpassed tocreate_subprocess_limited, would pin both.file_lockalso passes as a no-op. - A child started from the
sandboxed_argvresult gets no resource limits. The section 40 "Not in it yet" list does not name the streaming spawners (popen_limited,create_subprocess_limited) or the other names the body defers.
Problem / Motivation
Goal: An app backend, in the gateway process or spawned by it, calls a public, documented SDK for the gateway's own sensitive-path check, no-follow read, atomic write, redaction, audit row, sandboxed child and process helpers, instead of looking up private
kiro_crewnames.The app repositories under the #26967 campaign reach the gateway through
backend/_host.pyshims that look up private names by string (kiro_crew.security.is_sensitive_path,kiro_crew.sandbox.sandboxed_spawn_argv,kiro_crew.hooks.safe_read_file_bytes_nolink, ...). Each name moves with the wheel, so each lookup is a gap in that repository'sPORTING.md, and the owner ruling in comment 6841699202 (item 6) asks for those names to become public seams before the wheel copies are deleted.Why it matters
While a former built-in depends on a private name, its wheel copy cannot be deleted, and a refactor of that name silently disables the app's feature on the next upgrade (the shim refuses when the lookup fails). A public surface with the gateway's own semantics lets the app repositories drop those gaps without copying security controls into app code, where they would drift from the ones the gateway enforces.
Not a goal
What changed (motivation → approach → change)
I collected every private name the app repositories reach through
_host.py(an AST scan of all 13 shims, plus the host-import tables in aws-control, ops-mission-control, design-critique and auto-improvement), grouped them by control, and picked the groups the most apps use: sandboxed spawn (7 apps), process and lock helpers (7), atomic write and owner-only dirs (7), redaction (6), sensitive paths (4), no-follow reads (4), audit (3).kiro_crew.apps.backend_sdk(src/kiro_crew/apps/backend_sdk/) is a new package of thin delegates, one module per group. Each name calls the private control on its facade module at call time, so a later tightening reaches the app, and raises the gateway's own exception classes (FileTooLargeError,SandboxUnavailableError). Public signatures carry only the parameters the apps pass and none that adds reach: the spawn helpers accept thestandardandstricttiers and refuse every other value before preparing, none of the private chokepoint's mask-lifting or write-window parameters is offered, andrun_sandboxedforwards only thesubprocess.runkeywords inspawn.RUN_KWARGS(stdio,cwd,timeout,check, text decoding), refusingprofile,executable,pass_fdsand every other one withTypeError. The SDK spawns nothing unsandboxed:run_sandboxedandrun_sandboxed_asyncprepare throughsandboxed_spawn_argv, run under the resource limits with the scrubbed environment, and remove the launcher on every outcome. The async one starts the child in its own process group on POSIX and reads that group id while the child is alive, so a timeout or cancel kills its descendants too, one that outlived the child included; the sync one kills the child (its tree on Windows) and its docs point a backgrounding child at the async form.scrub_outboundandaudit_logare the samectx.scrubandctx.auditimplementations for code with no context;audit_log()takes the spawned backend'sKIROCREW_APP_NAMEand refuses to build a writer with no name. Names bind on first access, so a spawned backend loads nothing it does not call.The package is an App Kit seam level 7 addition: #33589 already raised
APP_SDK_LEVELto 7 on main, so this PR adds its row to the level-7 list and leavessrc/kiro_crew/apps/app_sdk_level.pyandwebsite/src/app-sdk/sdkLevel.tsalone.scripts/adoption_pin.pycounts a non-test file that names bothkiro_crewandbackend_sdk, in any import form or string lookup, as a level-7 use. Spec: app-kit-platform.md §40 (and the §32 and §33 level notes); authors: api-reference.md "Backend SDK".Seam level. Per the driver decision in #26967 (comment 6844003956), every seam of this batch is a level-7 seam: the first to merge (#33589) raised the level, and the rest keep 7 and add their row. A host can report 7 before every level-7 seam has merged, so an app feature-detects this package by its import, as the api-reference example does.
Left for a later SDK round (still private, still a
_host.pygap): chat slot and auto-nudge internals (the app-owned chat slot seam, ruling item 4),pinned_fsdescriptor helpers,link_unfurlURL vetting,messaging.raster.sniff_raster_mime,asset_downloader.download_to,executors.subprocess_executor,apps.registry.minimal_env,config.loaderandconfig.paths,security.redact_local_pathsanditer_credential_matches, the remainingatomic_writeandowner_only_fileshelpers,sandbox.effective_sandbox_mode,loop_lock.LoopBoundLock,user_json.loads_user_json, and the domain modules (crew_log,knowledge,deploy,transcribe,vector_memory,cron,notifications.bus,llm_helpers,shared_crewgates).Backwards compatibility
Compatible: the package is new and no existing name, signature, default or level changes; a host or app that never imports the package behaves as before.
Removes nothing: the diff only adds a package, doc sections and pin-tool cases.
Tests
test/test_app_backend_sdk.py: every public name resolves; a real spawned child imports the package on the gateway interpreter without loadingkiro_crew.sandboxorkiro_crew.hooksand answers the path gate; the path checks answer like the gateway gate and delegate at call time; the read returns a plain file and refuses a symlink, a hardlink, an escape fromwithin_rootand a sensitive path, and raises the gateway'sFileTooLargeError; atomic write and owner-only modes;scrub_outboundequalsctx.scrub.outbound;audit_logattribution and refusal with no name;sandboxed_argvforwards only tier, env and the Python strip, refusesoff/auto/cc/workflow/empty before preparing, and has no widening parameter (sync and async);run_sandboxedruns the wrapped argv with the scrubbed env, forwards every listed keyword, refusesprofile/executable/pass_fds/close_fds/preexec_fn/shell/userbefore preparing, removes the launcher on success and on a raise, and refuses another tier;run_sandboxed_asynccaptures a real child's output, starts a real child as its own process-group leader on POSIX, kills a real backgroundsleepthe shell left holding the pipes after the shell itself exited, and kills the child past its deadline, removing the launcher both times; platform flags, link helpers,rmtree_force,file_lockandkill_and_reapdelegate.test/test_builtin_adoption_pins.py: the pin tool reports the package at level 7 for a dotted import,from kiro_crew.apps import backend_sdk(plain and parenthesized), an attribute of the imported parent and a string lookup; it ignores amy_backend_sdkname and anything undertests/.test/test_app_sdk_level_mirror.pykeeps the two level constants equal.Each test fails without the change it covers.
prove.pyreports INCONCLUSIVE (reverting every production hunk removes the package, so the run errors at collection), so each hunk was mutated by hand instead: the tier check off (7 fail), the keyword check off (7 fail),start_new_sessionoff (1 fails), the captured group kill off (1 fails: the background sleep outlives a 60 s wait), the pin scan back to the dotted name only (3 fail), the launcher left behind (4 fail), a nameless audit writer allowed (3 fail).Determinism: the new spawn and pin tests passed 20 runs, each in a different shuffled order under
-n0, and both files pass under-n 4beside their neighbours (131 passed);test/test_flake_pattern_ratchet.pypasses. The one short deadline (timeout=0.01) waits on an Event nobody sets, so it always expires and carries# flake-ok; every other bound iskiro_crew.testing.wait.FALLBACK_TIMEOUT_SECS.Manual verification
Ran the new and touched tests plus
test/test_spawn_audit.py(162 passed) from the worktree with the gateway interpreter, and flake8, isort, black, mypy, the comment-history, brand, harness-parity, line-cap and docs-lint gates. N/A beyond that: there is no UI and no runtime path changes until an app imports the package.Related Issues
Part of #26967
Owner ruling: #26967 (comment) (item 6).
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement