feat(sdk): compose hosted Garden Babysitter

[AgentRelayBot]

The canonical Software Garden could load the reviewed native Babysitter artifact and the capability sandbox could execute it, but hosted callers had no single composition boundary. They had to pair base and installation authority themselves, while the ordinary authored loader correctly refused hosted handlers because it imports tenant JavaScript in the host.

This adds runHostedSoftwareGardenBabysitter, which atomically captures the exact reviewed Garden source and complete lock-backed extension installation as one opaque generation, then executes the matched handler through the existing Linux capability sandbox. The ordinary authored executor remains fail closed. A deterministic inventory test pins the published artifact coordinates; Linux cases cover missing artifacts, digest drift, wrong routes, queued/duplicate receipt replay, capability refusal, and the successful composed path.

The catalog handoff now reflects the product decision that Babysitter is a first-class Recommended Flow extension related to Software Garden. Discovery remains separate from activation. Cloud #4002 still names relay:hosted-flow-extension:v1 as the external owning-runtime dependency; activation must remain blocked until that runtime calls this entrypoint and a live original-session receipt is captured.

This deliberately avoids every path owned by open PR #584. Its later Software Factory digest repin is consumed dynamically through loadHostedExtensionRuntime.

Local verification

Command:

$ npm run typecheck --prefix packages/sdk

> @relayflows/sdk@2.0.33 typecheck
> tsc --noEmit && tsc -p tsconfig.type-tests.json

Command:

$ cd packages/sdk && npx vitest run tests/software-garden-babysitter-composition.test.ts tests/flow-extension-compose.test.ts

 RUN  v2.1.9 packages/sdk

 ✓ tests/software-garden-babysitter-composition.test.ts (6 tests | 5 skipped) 53ms
 ✓ tests/flow-extension-compose.test.ts (22 tests) 8969ms

 Test Files  2 passed (2)
      Tests  23 passed | 5 skipped (28)

The five new skipped cases require Linux and /usr/bin/bwrap; this macOS run is inventory/composition evidence, not sandbox execution evidence. The repository's linux-x64-artifact CI job is the runnable E2E gate.

Command:

$ git diff --check
# no output; exit 0

No merge, publish, release, catalog mutation, activation, or deployment is performed here.

---

Note

Medium Risk
Adds the security-sensitive hosted composition path for native Babysitter execution; behavior is gated by existing sandbox checks and new fail-closed tests, but no production runtime wires the entrypoint yet.

Overview
Introduces runHostedSoftwareGardenBabysitter, the canonical hosted entrypoint for Software Garden + native Babysitter. Callers pass a flowPath only; the SDK loads base and lock-backed installation as one generation via loadHostedExtensionRuntime, then runs the matched handler through the existing Linux capability sandbox. The ordinary authored executor stays fail-closed (plugin_unsupported); comments and exports document that hosted delivery must use this boundary instead of pairing authorities manually.

docs/BABYSITTER-CATALOG-HANDOFF.md is updated to treat Babysitter as a first-class Recommended Flow extension, name this entrypoint as the activation prerequisite, and point Cloud #4002 at the external Relay/Flows runtime that must call it before lineage reaches relay:native-existing-session:v1.

New software-garden-babysitter-composition.test.ts pins reviewed artifact coordinates in the lockfile and adds Linux fail-closed cases (missing install, digest drift, unroutable events) plus optional bwrap cases for successful execution, receipt replay, and capability refusal.

^{Reviewed by Cursor Bugbot for commit c4a655d. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Summary by cubic

Adds runHostedSoftwareGardenBabysitter, a single composition entrypoint that captures the reviewed Software Garden source and its lock-backed Babysitter installation as one opaque generation and executes the matched handler through the Linux capability sandbox. The ordinary authored executor stays fail closed because it imports extension JavaScript in the host, so hosted callers previously had to pair base and installation authorities by hand.

Rollout and catalog

• The catalog handoff now classes Babysitter as a first-class Recommended Flow extension related to Software Garden; discovery stays separate from activation.
• Activation remains blocked until Cloud #4002 calls this entrypoint and a live original-session receipt is captured.

Tests

• A deterministic inventory test pins the reviewed artifact's commit, digest, and manifest hash as the only composition member.
• Linux sandbox cases cover missing artifacts, store digest drift, unroutable deliveries, capability refusal, and queued/duplicate replay with a stable delivery identity and extension authority.

^{Written for commit c4a655d. Summary will update on new commits.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 8350c354-c02d-43b9-91af-4efd1c9ccb76

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AgentRelayBot]

@codex review

Please perform a fresh independent full-diff review of exact base 66eb9a932239af0a4d2e318b64607010b1f6c474 through exact head 41d416e75d26ee65bb4e6e7023dba3d99a312221. Review the canonical composition boundary, fail-closed artifact/generation/capability behavior, idempotent replay receipts, deterministic inventory pins, Linux E2E coverage, and whether the documented external Cloud blocker is exact. Please report an explicit GO or actionable findings tied to this exact head.

[chatgpt-codex-connector]

To use Codex here, create a Codex account and connect to github.

[kjgbot]

REQUEST_CHANGES — exact review range 66eb9a932239af0a4d2e318b64607010b1f6c474...41d416e75d26ee65bb4e6e7023dba3d99a312221.

1. The changed handoff names the wrong owning runtime boundary. docs/BABYSITTER-CATALOG-HANDOFF.md tells hosted callers, and then Cloud specifically, to call runHostedSoftwareGardenBabysitter; it points only to merged Cloud #3942. But Cloud #4002 at 25412782bf148ff8dd8018bdbafd719d4e8347fa says the opposite operational split: Cloud supplies no execution authority, step 4 belongs to an exact-target owning Relay/Flows runtime exposing relay:hosted-flow-extension:v1, and relay:native-existing-session:v1 is downstream delivery only. The PR body says the handoff reflects this blocker, but the file never names #4002 or relay:hosted-flow-extension:v1:

$ rg -n "4002|hosted-flow-extension|3942" docs/BABYSITTER-CATALOG-HANDOFF.md
61:... Cloud PR #3942 owns the ...

Please make the handoff state the actual owner split and keep activation blocked until that capability is merged, deployed, and proven against a private repository. As written, it can send the next implementer toward the direct/on-demand Cloud host path that #4002 explicitly forbids. Also fix the nearby typo It is is reached.

2. The advertised replay test does not replay a delivery. software-garden-babysitter-composition.test.ts labels the case as preserving queued/duplicate replay receipts, but iteration 1 uses delivery-1 / bst_111... and iteration 2 uses delivery-2 / bst_222.... Those are unrelated deliveries, so the test would stay green without preserving same-delivery replay identity. Exercise the same deliveryId twice, return queued then duplicate with the stable receipt identity, and assert both capability requests plus branded dispatch authority retain that same delivery. Postgres can remain the sole dedupe authority; this test should prove boundary preservation, not SDK-owned dedupe.

Verification evidence:

$ git rev-parse HEAD
41d416e75d26ee65bb4e6e7023dba3d99a312221
$ git merge-base 66eb9a932239af0a4d2e318b64607010b1f6c474 HEAD
66eb9a932239af0a4d2e318b64607010b1f6c474
$ git ls-remote origin refs/pull/585/head
41d416e75d26ee65bb4e6e7023dba3d99a312221 refs/pull/585/head

Exact-head dependency install followed by npm run typecheck --prefix packages/sdk: PASS.

$ vitest run tests/flow-extension-compose.test.ts
Test Files  1 passed (1)
Tests       22 passed (22)

$ vitest run tests/software-garden-babysitter-composition.test.ts
Test Files  1 passed (1)
Tests       1 passed | 5 skipped (6)  # macOS, expected

Ubuntu job 108822284731 is green and actually executed all six composition cases with no skips; its full SDK result is 218 passed | 1 skipped files and 3510 passed | 4 skipped tests. All required PR checks are terminal green and GitHub reports CLEAN.

I separately traced the artifact/base same-generation rechecks, store/manifest digest verification, missing-artifact and wrong-route refusal, single-call capability denial propagation, exact native permission/budget pins, base source digest pin, private Linux sandbox snapshot, and the ordinary host-importing loader refusal. Those paths are fail-closed at this head; the two items above are the remaining blockers to the PR claims.

[kjgbot]

GO — exact review range 66eb9a932239af0a4d2e318b64607010b1f6c474...c4a655d498ae59354918c1591a8e149cfc7bfafe.

No blocking correctness or security findings remain.

Prior review 5335195090 is addressed:

1. The handoff now names Cloud #4002 at exact head 25412782bf148ff8dd8018bdbafd719d4e8347fa, states that Cloud supplies no execution authority, assigns the canonical entrypoint to the external exact-target Relay/Flows owner of relay:hosted-flow-extension:v1, identifies relay:native-existing-session:v1 / merged Cloud #3942 as downstream only, and keeps activation blocked until the owner is merged, deployed, and a private-repository live receipt exists. I independently checked Cloud #4002 and #3942; those statements match their current contracts and state.

2. The Linux replay case now invokes the wrapper twice with the identical delivery-replay dispatch/input identity, returns queued then duplicate under the same bst_111... receipt identity, and asserts that both capability requests and both branded dispatch authorities retain that delivery ID plus identical pinned extension provenance. It does not claim SDK-owned dedupe; the adapter supplies the two statuses.

Full-diff audit:

• runHostedSoftwareGardenBabysitter loads base plus installation through the opaque same-generation loader and immediately passes those authorities into the existing capability runner. The runtime is rechecked after private snapshots and before launch.
• Complete declaration/lock order, stored artifact digest, manifest hash/name/version, exact Babysitter ref/digest/manifest, base source hash/name/version, trigger route, compatibility, capability-only permissions and budget (codex, $1, 5m), and Surface runtime bytes remain pinned. The native handler performs no model/agent call, so no model-selection authority is introduced by this path.
• Missing installation, digest drift, ambiguity/wrong route, malformed authority/input/request/receipt, stale generation, and capability denial all fail closed before or at the single capability call. There is no retry/fallback here. The ordinary host-importing authored executor still rejects matched handlers with plugin_unsupported.
• The deterministic inventory test pins the sole source SHA/path, artifact digest, and manifest digest. The exact-head Ubuntu job proves the Linux/bwrap execution, replay, denial, private snapshot, and capability confinement paths.

Verification:

$ npm run typecheck  # packages/sdk
exit 0

$ npx vitest run tests/software-garden-babysitter-composition.test.ts
Test Files  1 passed (1)
Tests       1 passed | 5 skipped (6)

$ npx vitest run tests/flow-extension-compose.test.ts
Test Files  1 passed (1)
Tests       22 passed (22)

$ git diff --check 66eb9a932239af0a4d2e318b64607010b1f6c474...c4a655d498ae59354918c1591a8e149cfc7bfafe
# no output; exit 0

The five composition skips above are the expected macOS Linux/bwrap cases. A broader local command that included the Linux-only isolation/native suites failed locally with hosted extension isolation requires Linux; it is not used as acceptance evidence. Exact-head GitHub Actions job 108828723986 ran on Ubuntu with bubblewrap and passed: composition 6/6, hosted isolation 22/22, native extension 41/41, flow-extension compose 22/22; full SDK result 218 passed files / 3,510 passed tests (four declared unrelated skips), followed by successful standalone artifact build and smoke.

At submission, refs/pull/585/head is still c4a655d498ae59354918c1591a8e149cfc7bfafe, main is still 66eb9a932239af0a4d2e318b64607010b1f6c474, all required exact-head checks are terminal green, and GitHub reports MERGEABLE. This approval does not claim deployment, activation, private-repository proof, publication, or rollout readiness.