Skip to content

fix(apps): register nothing when an agent template cannot be read - #34142

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/32688-template-read-oserror
Nov 11, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/32688-template-read-oserror

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An app agent whose template file cannot be read for a moment is never registered with its placeholders still in it; the read failure is reported so a retrying caller registers it properly later.

When the gateway could not read an app's agent template at render time, it handed the unread template back to the caller as if no rendering were needed. If the file was readable again a moment later (on Windows, an antivirus scan or a sync client holding a just-extracted file), the caller read the raw template and registered it: the agent config named {UV_BIN} as its MCP server command, and no failure was reported or logged.

Why it matters

The registered agent cannot start its own MCP server, so it cannot reach its tools. The broken config stays until the next registration (a gateway restart, or disabling and re-enabling the app), and nothing in the log points at the cause. Callers that retry on I/O failures saw a success, so they never retried.

Not a goal

  • Changing how a template that is not UTF-8 is handled: the caller still skips it without reporting it.
  • Removing the second read in _register_agents (handing the template text instead of a path), which would change the helper's return type for every caller.
  • Detecting leftover placeholders in an already-registered config.

What changed (motivation → approach → change)

A template that could not be read was registered with its raw placeholders when the read worked again a moment later. The cause was the read-error arm of _render_shipped_agent in apps/bridges_agents.py: it returned the template's own path on any OSError, assuming the caller's second read of that path would fail too and report it.

A read OSError is now handled like the write failure in the same function: it logs a warning, adds the template to io_failures and returns None, so nothing is registered and retrying callers try again. A UnicodeDecodeError keeps the old path, because the caller's second read fails the same way and skips the agent.

Backwards compatibility

Compatible: a template that reads fine renders and registers as before; only a read that fails at render time changes, from registering whatever the next read finds to registering nothing and reporting the failure, which is what a read that fails a few milliseconds later already did.

Removes nothing: no key, route, file or function is removed; the change is the outcome of one error arm.

Tests

  • test_a_read_failure_registers_nothing_even_if_the_next_read_succeeds (in test/test_app_bridges_agent_configs.py): the first read of a templated agent raises PermissionError and the next succeeds; _register_agents registers nothing, writes no config and reports the template in io_failures.

Proof: PROVEN test/test_app_bridges_agent_configs.py::TestRenderFailureIsClassifiedByCause::test_a_read_failure_registers_nothing_even_if_the_next_read_succeeds (head 2df1f7afcee8)

Manual verification

N/A — unit coverage sufficient: the defect is a timing window between two reads of one file, which the test reproduces deterministically by failing the first read.

Related Issues

Closes #32688

Sibling sweep

Swept: git grep -nE "except ((OSError, UnicodeDecodeError|UnicodeDecodeError, OSError))" -- src/kiro_crew/apps/
Siblings: none -- every other match returns a value its caller does not read the same file for again

Pattern harvest

Not generalizable: the defect is one helper returning its unread input for the caller to re-read; no other render or read helper in the app bridges hands an unread path back.

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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 9, 2026 21:53
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 74fa5e18d55758db5f434196f8688f30997e6f51 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 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. A read OSError now goes through the same steps as the write failure: log it, add it to io_failures, return None. The only caller, _register_agents, already skips on None.

Notes

  • The leftover second read in _register_agents is what opened this window, and the description lists removing it under "Not a goal". Passing the template text to the caller instead of a path would close the same race for the UnicodeDecodeError arm and any future arm. It's a follow-up, not something to change here.

[DESIGN-REVIEWED] 74fa5e1

Description read

[DESCRIPTION-READ] 3c3fb90b99785d3439ff22ae68bec6430442e1accd0cd885f08c6d2b3fb27ba9

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 74fa5e18d55758db5f434196f8688f30997e6f51 — 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 to check.

What this change ships

Inventory (3 items) — 3 justified

Intent: when an app agent's template can't be read for a moment, the agent shouldn't get registered with its raw {UV_BIN}-style placeholders, and the caller should be told so it can retry. This is a FIX (Closes #32688; the added test fails on base).

  1. If the template can't be read at render time, nothing is registered and the read failure is reported in io_failures instead of passing silently — justified
  2. That read failure now logs a warning naming the app and the agent file — justified
  3. The docstring and test-class text now say there are four None reasons, two of them retryable (it was three, one) — justified

[FIRST-PRINCIPLES-REVIEWED] 74fa5e1

Description read

[DESCRIPTION-READ] 1272ec8a9abd1dedd15dc8e7d27fb95e2fdd79080a79aa65d7179708ae91cf5d

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 74fa5e1

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

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

@bolichen97
bolichen97 enabled auto-merge (squash) November 9, 2026 22:18
@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 9, 2026
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 74fa5e18d55758db5f434196f8688f30997e6f51 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 74fa5e1

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

@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 10, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approve on b34be91. A read OSError in _render_shipped_agent now logs, reports to io_failures and returns None (same as the write-failure arm), so a template that is locked for a moment is never registered with raw {UV_BIN} placeholders; the only caller already skips on None. Decisive lines: src/kiro_crew/apps/bridges_agents.py:883-889, src/kiro_crew/apps/bridges_agents.py:1003-1007, test/test_app_bridges_agent_configs.py:1401-1420

@bolichen97 bolichen97 closed this Nov 10, 2026
auto-merge was automatically disabled November 10, 2026 17:26

Pull request was closed

@bolichen97 bolichen97 reopened this Nov 10, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Closed and reopened with no code change: PR Readiness was waiting on a Code Review run that records its base (the #33337 rule), and only a new pull request event starts one. The close turned auto-merge off; it is re-armed once this re-run is green.

@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 10, 2026
A read error on an app's agent template made the render hand the
unread template path back to the caller. When the error cleared before
the caller's own read (a Windows sharing violation, an antivirus scan),
the template registered with its literal placeholders and no I/O
failure was reported, so no retrying caller tried again.

The render now treats a read OSError like its write failure: it logs,
reports the template in io_failures and registers nothing. A template
that is not UTF-8 keeps its old path.

Closes #32688
@bolichen97
bolichen97 force-pushed the fix/32688-template-read-oserror branch from b34be91 to 74fa5e1 Compare November 11, 2026 05:52
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in setup.cfg since this head went green (69d3a9a -> c220308); CI re-running.

The red Backend Tests shard 4 on Linux, Windows and macOS was main's: test/test_session_markdown.py::test_a_condition_one_opener_is_closed_as_the_parser_reads_it[long-s] failed on main with markdown-it-py 4.3.0 until #34646 kept it below 4.3. This head carries that fix; the PR's own change is byte-identical. The Backend Tests (Windows) (6) red is the known flaky test tracked in #34376.
[operator: bolichen97]

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 11, 2026
@KiroCrewCaptain
KiroCrewCaptain merged commit e756779 into main Nov 11, 2026
132 of 144 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/32688-template-read-oserror branch November 11, 2026 12:04

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

Tier 1 auto-approve: fix (2 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: a transient OSError reading an app agent template now registers nothing and is reported as a retryable io_failure instead of registering the unrendered template; covered by a new test.

@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 11, 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.

apps: a transient read failure on an app agent template registers the unrendered template, with its literal placeholders and no io_failures entry

3 participants