Skip to content

feat(hooks): Kiro Space app source may post into a bound shared session (preview, off by default) - #35302

Closed
chenmingwei23 wants to merge 1 commit into
mainfrom
mkt-app/gap2-ks-app-hooks
Closed

chenmingwei23 wants to merge 1 commit into
mainfrom
mkt-app/gap2-ks-app-hooks

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A person in a Kiro Space app can post a turn into a session their host machine chose to share, and the agent sees who wrote it.

Today an app-mapped webhook source has no way to reach a bound shared session, so a shared session cannot take input from the people it is shared with. This adds that path as a preview, off by default.

Why it matters

Without it the shared session is read-only for everyone but the host. With it the host can let named people post, while every other source stays refused on a bound key.

Not a goal

  • No change to who may bind a session, and no new binding surface.
  • No chat-channel or notification delivery for turns on a bound session.
  • No default-on behavior: the Shared Crew preview and the room switch must both be on.

What changed (motivation → approach → change)

A token minted with app=kiro-space may post to a hook:ks-session:* key, and only when that key is bound. The author comes from the body (userId, displayName), is cleaned and bounded, and is stamped on the transcript row. The agent is told these are another person's words. The preview off, the room switch off, or a config read error all read as off. A registry read error answers 503. A bound session keeps its transcript after the turn (released, not reset). Any other source on a bound key is refused, and the hook:ks-session: prefix is reserved for every source. A new room config flag (default off) is added and config-baseline.json is regenerated.

Backwards compatibility

Compatible: the new path needs the preview, the room switch and an app-mapped token, all off today. The one tightening is that a hook:ks-session: key not in the bound shape is now refused.
Reader: src: hook:ks-session -- app, cron, chat -- no reader of that prefix exists on origin/main (git grep over src and website/src finds none), so no existing key is refused.

Tests

  • test_hooks_ks_app_bound_session*.py: author cleaning, check order, preview and room switches, config read error, registry 503, reserved prefix, log lines.
  • test_shared_crew_room_principal.py: the room principal.
  • test_config_baseline.py and test_facade_mirror_guards.py pass with the new flag and the patched names going through the config facade.

Manual verification

N/A -- unit coverage sufficient: the path is a webhook handler with no UI.

Related Issues

None.

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

Contributions are accepted under the project's Apache-2.0 license.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 11, 2026
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🔴 BLOCK

Premise-level review of cc14676a8d4b0aaae5f5bd27a1219ee9eae76fad — 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: BLOCK

Nothing in src/ ever binds a key, so every app post is refused with session_key_unbound. The Goal is not reachable, and a webhook path that never succeeds still adds a permanent config key, an enum value and a reserved prefix.

Notes

  • Item 2 — inherited: APP_KIRO_SPACE = "kiro-space" and Provenance.KIRO_SPACE_ROOM hard-code one app's id in core. AGENTS.md says "core never … hard-codes a specific app (… an app id)". Subtraction: drop the app id and use the existing app-token identity (chat_slot_sdk._APP_TURN_ACTOR, app:<name> principal).
Inventory (7 items) — 3 justified

Intent: let people in a shared session post turns that are attributed to them. This is an ADDITION.

  1. App-mapped token posts into a bound hook:ks-session:* key — zero consumers (no binder)
  2. A token can be minted with app=kiro-space — one consumer, generalized (KNOWN_TOKEN_APPS has one entry)
  3. New dashboard.shared_crew.room switch, off by default — justified
  4. The hook:ks-session: prefix is refused for every other source — justified
  5. Turn rows record the author; the agent's prompt carries a "[Message from …]" header — justified
  6. A bound session keeps its transcript after the turn — zero consumers (no session is ever bound)
  7. room_sessions.json registry with bind/unbind — zero consumers

Blockers

The feature cannot be reached: nothing binds a session — zero consumers
Trigger: I grepped bindings()|RoomSessionBindings|room_sessions.json over src/ and found 0 callers of bind/unbind. The only use is is_bound, at hooks.py:132. The module docstring says "When this machine shares a session it binds the session's key", but no code does that, and ## Not a goal rules out "new binding surface".
Outcome: With both switches on, every app post returns 403 session_key_unbound. Even so, the room key, KIRO_SPACE_ROOM, the token app field and the reserved prefix ship as permanent surface.
Subtraction: remove items 1, 2, 5, 6 and 7, and the room flag, until a binder exists in this PR or on base.
Clears when: a non-test caller of RoomSessionBindings.bind exists in src/ on this head or on the base.

[FIRST-PRINCIPLES-REVIEWED] cc14676

Description read

[DESCRIPTION-READ] 700fa5f7160a5ef76880afcc671e2e5d89bb2235303910fffd6fc902cfb5c402

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 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision cc14676a8d4b0aaae5f5bd27a1219ee9eae76fad 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 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The path is off by default, refuses anything outside its narrow case, and is easy to revert. But nothing in it can be used yet.

Notes

  • No production code calls RoomSessionBindings.bind(). Only the tests do. With no binding path, the only way a key gets bound is a hand-edited room_sessions.json, so every app post returns session_key_unbound. The description says "No change to who may bind a session", which reads as if a binding path already exists. Either name the follow-up PR that adds binding, or reword that line.
  • The diff changes no spec. Shared-crew principals and provenance, the webhook token app field, and the reserved hook:ks-session: prefix are documented behavior, so shared-crew.md and the webhook or messaging spec should be updated in the same commit, as AGENTS.md requires.
  • Core now hard-codes APP_KIRO_SPACE in webhooks.py and Provenance.KIRO_SPACE_ROOM. If Kiro Space is an App Kit app and not an external service, this is an app id in core, which the no-built-in-apps rule forbids. A generic "app-mapped token may post to a bound key" seam would avoid that.

[DESIGN-REVIEWED] cc14676

Description read

[DESCRIPTION-READ] 3e69be5aa958eb75cf706324b58830162002d17495f6f608522e7b0f7a103c80

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 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] cc14676

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

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

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — 🔴 changes requested (blocking)

GPT 6.1 found at least one blocking issue that must be resolved before merging cc14676a8d4b0aaae5f5bd27a1219ee9eae76fad. Adjudication produced no [GPT-ADJUDICATED] marker for cc14676: the adjudication stage FAILED TO RUN (its raw output is in the Adjudication details block -- typically an API or setup error), so no proportionality review took place and GPT's blocking verdict stands unreviewed.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/shared_crew/room_sessions.py:82 -- The agent can rewrite the host’s sharing allowlist

return self._base / _FILENAME
Trigger: With room posting enabled, a sandboxed agent writes a chosen key into room_sessions.json; an app-mapped webhook then passes _bound_session_gate using that forged binding.
Outcome: The webhook starts work in a session the host never authorized for sharing. The existing webhooks directory mask does not cover this root-level file.
Anchor: residual/security
Fix: Store the gateway-owned registry inside the already-masked webhooks directory, without adopting bindings from the agent-writable location.

BLOCKING -- src/kiro_crew/dashboard/handlers/hooks.py:1326 -- Timed-out bound turns leave backend work running

if author is None:
Trigger: A bound turn times out before the circuit-breaker threshold while its ACP backend is still working; wait_for cancels the consumer, and AcpSessionHandle.prompt records an abandoned prompt without cancelling the backend.
Outcome: The runner reports timeout and releases capacity while backend work continues; cancellation waits until another prompt reaches the session.
Anchor: residual/guard-removal
Fix: Recycle timed-out or interrupted bound runtimes without clearing their conversation; skip teardown only after successful completion.

BLOCKING -- src/kiro_crew/webhooks.py:63 -- Core makes shared-session posting specific to one app

APP_KIRO_SPACE = "kiro-space"
Trigger: Token creation restricts app to KNOWN_TOKEN_APPS, and _bound_session_gate grants shared-session posting only when that identity matches.
Outcome: Another registry app cannot use this capability without changing and releasing core, contrary to the required app-agnostic App Kit seam.
Anchor: no-new-builtin-apps
Fix: Authorize posting through a generic host-assigned source capability and keep the app-specific adapter in its app repository.

BLOCKING -- src/kiro_crew/dashboard/handlers/hooks.py:681 -- Human room authors share the automation budget

**bound_kwargs,
Trigger: With fair admission enabled, per-person concurrency one, and available Crew-wide capacity, two different room authors post to different bound keys; _run_hook_agent calls run_admitted_or_raise with automation=True and no author budget.
Outcome: The second person queues behind the first despite unused personal capacity, and both people’s work is charged to automation.
Anchor: defect
Fix: Pass the accepted author’s principal ID as budget_key for bound turns, retaining automation charging for ordinary webhooks.

[BLOCK-MERGE] cc14676
[GPT-REVIEWED] cc14676
False positive or not applicable? A repository writer can comment:
/ai-review override gpt cc14676a8d4b0aaae5f5bd27a1219ee9eae76fad false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 11, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

TALOS security review of the bound shared-session hook path, patches 0001-0004 (95db48c..e9aa86b): ACCEPT-WITH-NITS. No blocking finding. The push can go ahead now; the items below ride in the same push.

A non-author reviewer applied the four patches to a clean checkout, ran the two new test files (51 pass) and 16 hand-made mutations, and probed the real handler. TALOS read the findings and signs them.

Holds: only an owner-minted app="kiro-space" source can reach the path, and only for an exact bound key. app cannot be set by a request field or changed by PATCH. Both switches default off and a read error counts as off. The author name is cleaned (control, format and separator characters removed, 128-char cap), the user id is held to a strict alphabet, and the stored provenance is fixed in code, so a body cannot forge an owner turn. Logs carry no token, signature or author text. Kill switch, throttle, auth, pause, body cap and signature run before the gate. The one-turn-per-key 409 runs after the gate by design (a refused request must not claim the key); that is accepted.

Please include in the same push (all small):

  1. PR body: the known limit (the author is the app's word, so a stolen app-source credential can write as any user into any bound session; revoke through the owner-only token PATCH/DELETE), the stated dependency that who may post is decided only by the Kiro Space side, and one line on the unbind window (a post that passed the gate just before an unbind still runs one turn).
  2. A test that an unreadable registry gives 503 for both an app and a plain source (a mutation that treats a read error as "unbound" currently survives all tests).
  3. Route-level tests: owner-only mint with app, app_invalid for an unknown value, PATCH with app is refused.
  4. Reserve the hook:ks-session: prefix for every source: a key with that prefix that is not the exact bound shape is refused (a suffixed, space or newline variant is currently accepted as an ordinary key). Add a test with such a key.
    Optional hardening, not required: scope app-mapped tokens to bound keys only, and refuse unsigned app-mapped mints.

Not covered: CI after the local commits, the Kiro Space side that decides who may post, a full-suite regression run, and a real host with a live agent turn. Sign-off is for this patch range only; a different head needs a delta ask.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 12, 2026
@chenmingwei23 chenmingwei23 changed the title hooks: Kiro Space app token may post into a bound shared session (preview, off by default) feat(hooks): Kiro Space app source may post into a bound shared session (preview, off by default) Nov 12, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 12, 2026
…on (preview, off by default)

Adds a bound shared-session path for the app-mapped hook source. Off by default; preview, room switch and config read errors all read as off. Includes tests for the author cleaning, check order, switches and logs.
@chenmingwei23
chenmingwei23 force-pushed the mkt-app/gap2-ks-app-hooks branch from e2cbca9 to cc14676 Compare November 14, 2026 11:41
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Parked for a maintainer decision. This PR stays a draft, with no further pushes or reruns until then.

The blocking First Principles finding: nothing in src/ calls RoomSessionBindings.bind, so is_bound (hooks.py:132) is never true and every Kiro Space app post returns 403 session_key_unbound. Adding a binder, or shrinking the PR to drop the unreachable surface, changes what this PR is for, so that call belongs to a maintainer.

State at head cc14676: one commit on current main; the config-baseline and test-patching failures are fixed; the other red checks are shared rate-limit failures, not findings.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Closing. Nothing calls RoomSessionBindings.bind, so the is_bound check at hooks.py:132 is never true and the feature cannot take effect. It needs a binder design first; that will come as a new PR.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant