Skip to content

feat(app-kit): publish a backend SDK for an app's own python - #36341

Merged
bolichen97 merged 1 commit into
mainfrom
feat/w5-backend-sdk
Nov 13, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/w5-backend-sdk

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

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_crew names.

The app repositories under the #26967 campaign reach the gateway through backend/_host.py shims 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's PORTING.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

  • Changing any app repository: the apps adopt the SDK in their own PRs.
  • Covering every private name the apps reach: the less-used half is listed below and stays private for now.
  • New reach for an app: nothing here grants a permission, lifts a sandbox mask or widens a tier.
  • Changing any behaviour for a user or an app that does not import the package.

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 the standard and strict tiers and refuse every other value before preparing, none of the private chokepoint's mask-lifting or write-window parameters is offered, and run_sandboxed forwards only the subprocess.run keywords in spawn.RUN_KWARGS (stdio, cwd, timeout, check, text decoding), refusing profile, executable, pass_fds and every other one with TypeError. The SDK spawns nothing unsandboxed: run_sandboxed and run_sandboxed_async prepare through sandboxed_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_outbound and audit_log are the same ctx.scrub and ctx.audit implementations for code with no context; audit_log() takes the spawned backend's KIROCREW_APP_NAME and 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_LEVEL to 7 on main, so this PR adds its row to the level-7 list and leaves src/kiro_crew/apps/app_sdk_level.py and website/src/app-sdk/sdkLevel.ts alone. scripts/adoption_pin.py counts a non-test file that names both kiro_crew and backend_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.py gap): chat slot and auto-nudge internals (the app-owned chat slot seam, ruling item 4), pinned_fs descriptor helpers, link_unfurl URL vetting, messaging.raster.sniff_raster_mime, asset_downloader.download_to, executors.subprocess_executor, apps.registry.minimal_env, config.loader and config.paths, security.redact_local_paths and iter_credential_matches, the remaining atomic_write and owner_only_files helpers, 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_crew gates).

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 loading kiro_crew.sandbox or kiro_crew.hooks and 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 from within_root and a sensitive path, and raises the gateway's FileTooLargeError; atomic write and owner-only modes; scrub_outbound equals ctx.scrub.outbound; audit_log attribution and refusal with no name; sandboxed_argv forwards only tier, env and the Python strip, refuses off/auto/cc/workflow/empty before preparing, and has no widening parameter (sync and async); run_sandboxed runs the wrapped argv with the scrubbed env, forwards every listed keyword, refuses profile/executable/pass_fds/close_fds/preexec_fn/shell/user before preparing, removes the launcher on success and on a raise, and refuses another tier; run_sandboxed_async captures a real child's output, starts a real child as its own process-group leader on POSIX, kills a real background sleep the 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_lock and kill_and_reap delegate.
  • 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 a my_backend_sdk name and anything under tests/.
  • test/test_app_sdk_level_mirror.py keeps the two level constants equal.

Each test fails without the change it covers. prove.py reports 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_session off (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 4 beside their neighbours (131 passed); test/test_flake_pattern_ratchet.py passes. The one short deadline (timeout=0.01) waits on an Event nobody sets, so it always expires and carries # flake-ok; every other bound is kiro_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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 13, 2026 03:00
@bolichen97
bolichen97 enabled auto-merge (squash) November 13, 2026 03:00
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 2706d630d2e37bcf6411e99b6d3de57262de5e72 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 2706d630d2e37bcf6411e99b6d3de57262de5e72 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • spawn.py calls the private platform_compat._isolated_group_of_live_child, so the new public SDK depends on the same kind of private name it is meant to retire. Make that helper public in platform_compat, or move this group-kill logic there, so the next refactor cannot silently break run_sandboxed_async.
  • Once an app adopts a name, removing it breaks that app. The api-reference should say which names are stable and how one is deprecated before the first app repo adopts the package.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 2706d630d2e37bcf6411e99b6d3de57262de5e72 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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 ships

Inventory (8 items) — 8 justified

Intent: 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 kiro_crew lookups. ADDITION.

  1. An app backend can import kiro_crew.apps.backend_sdk and ask whether a path (or anything under a directory) is sensitive — justified
  2. An app can do a no-follow, root-confined read and an atomic or owner-only write with the gateway's refusals — justified
  3. A spawned backend without a ctx can redact outbound text and write audit rows attributed to its own app — justified
  4. An app can run a child in the gateway sandbox, limited to the standard or strict tier, sync or async, or only prepare it — justified
  5. An app gets the cross-platform kill, link, rmtree and file-lock helpers plus the platform flags — justified
  6. The adoption-pin tool now treats any non-test file naming backend_sdk as a level-7 requirement — justified
  7. The SDK_LEVEL / BACKEND_SDK_LEVEL constants let a context-less backend detect which seam level the host provides — justified
  8. App-author reference section and spec §40, plus the §32/§33 level notes — justified

[FIRST-PRINCIPLES-REVIEWED] 2706d63

Description read

[DESCRIPTION-READ] 96ad05a558942d4e7907a23f712aa35e38fe419a9c47e112a233a2744d1fad22

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 2706d630d2e37bcf6411e99b6d3de57262de5e72 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 2706d63

Verdict parsed from the review's SHA-scoped output markers for commit 2706d630d2e37bcf6411e99b6d3de57262de5e72.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 2706d630d2e37bcf6411e99b6d3de57262de5e72 false-positive: <reason, 20 to 500 characters>

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: no

  • span=ab2a95573096 Isolate async children before process-tree cleanup (src/kiro_crew/apps/backend_sdk/spawn.py)

fixed in ebc0c2a: run_sandboxed_async now starts the child with start_new_session=platform_compat.IS_POSIX, so kill_and_reap no longer skips the group kill and a timeout or cancel ends the child's descendants too.
Class swept: the only SDK path that promises a tree kill is run_sandboxed_async; run_sandboxed documents no descendant kill and keeps run_limited's behaviour, and sandboxed_argv* leave the run to the caller.
Pinned by test_run_sandboxed_async_starts_the_child_in_its_own_process_group (a real child reports pgid == pid; red with the flag off).

(This GPT verdict for e527733 was produced but never published: the installation token hit GitHub's rate limit while the lane posted it.)

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: no

  • span=125c9145fc15 Recognize SDK imports through the parent package (scripts/adoption_pin.py)

fixed in ebc0c2a: _seam_level_uses counts a non-test file naming both kiro_crew and the word backend_sdk, so from kiro_crew.apps import backend_sdk, its parenthesized form, apps.backend_sdk on an imported parent, a dotted import and a string lookup all pin at level 7.
Class swept: every spelling of the package other than the contiguous dotted name; the scan errs wide by design (a false hit only asks for a higher --min-sdk-level), and the word boundary keeps my_backend_sdk out.
Pinned by four new test_the_pin_tool_finds_every_seam_above_level_one cases plus a negative case; 3 fail with the dotted-name-only scan.

(This GPT verdict for e527733 was produced but never published: the installation token hit GitHub's rate limit while the lane posted it.)

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 2706d630d2e37bcf6411e99b6d3de57262de5e72 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2706d63

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 2706d630d2e37bcf6411e99b6d3de57262de5e72 false-positive: <reason, 20 to 500 characters>

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: run_sandboxed_async owns its child's process group and kills the group id it read while the child was alive

  • span=ab2a95573096 Timeout cleanup leaves descendants running after the leader exits (src/kiro_crew/apps/backend_sdk/spawn.py)

fixed in 78b4ca7: the group id is read right after spawn (platform_compat._isolated_group_of_live_child, the shared helper's own live-child guard) and SIGKILLed before kill_and_reap on timeout and cancel, so a descendant that outlived a reaped shell dies; the recycled-PID guard is kept because a group id cannot name another group while any member of this one lives.
Same span as the first round (2 hits): the approach moved from the shared helper's post-reap skip to the core pattern kill_process_group documents (a group id captured while the leader was alive), rather than patching another spelling.
Class swept: run_sandboxed (sync) kills the child on a timeout (its tree on Windows) and its docstring and api-reference row now point a backgrounding child at the async form; the public kill_and_reap delegate's docs state the post-reap boundary; sandboxed_argv* leave the run to the caller.
Pinned by test_run_sandboxed_async_cleanup_kills_a_descendant_that_outlived_the_child (a real sh -c 'sleep 600 &' whose shell has exited; red with the group kill off).

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 13, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

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).

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 13, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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):

  • The blocking black/isort/flake8/mypy job (ci.yml 'Backend Lint & Type Check') is red on this head, so none of the backend suites ran. That includes the new test_app_backend_sdk.py with its real-child process-group and sandbox spawn tests, the adoption-pin cases and test_spawn_audit.py. The descripti (src/kiro_crew/apps/backend_sdk/spawn.py, medium)

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 cc6f5f8434 · 1360 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

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
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased onto #36457 (187b4da): Backend Lint & Type Check (3.12) on cc6f5f8 failed on the mypy error in src/kiro_crew/cli_commands_memory.py:335 that main carried at 00c5418 and #36457 fixed; this PR does not touch that file. CI re-running on 2706d63.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 13, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Green-age note for 2706d63: green_age.py reports main +22 commits (187b4da -> 51349e1) touching files near this diff. Only docs/system-specs/modules/app-kit-platform.md is the same file (a hunk outside §32/§33/§40) and src/kiro_crew/apps/routes_install.py is an import edge; the rest are same-directory docs. Proved locally instead of discarding this green: git merge-tree against 51349e1 is clean, and with this commit cherry-picked onto 51349e1 test/test_app_backend_sdk.py, test/test_builtin_adoption_pins.py, test/test_app_sdk_level_mirror.py and test/test_spawn_audit.py pass (162 passed under -n 4), mypy is clean, and docs-lint shows only the unindexed-doc finding main already has. Re-syncs used: 1/3.

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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's sandbox_allow_unsandboxed_exec opt-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= in run_sandboxed_async. Removing either one leaves the suite green. A test that the async form refuses mode="off", plus a test that records the env passed to create_subprocess_limited, would pin both. file_lock also passes as a no-op.
  • A child started from the sandboxed_argv result 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.

@bolichen97
bolichen97 merged commit 9807bdd into main Nov 13, 2026
98 of 101 checks passed
@bolichen97
bolichen97 deleted the feat/w5-backend-sdk branch November 13, 2026 10:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants