Skip to content

refactor(agent-sdk): build the ACP provider through an SDK factory - #21545

Merged
dodgeblaster merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:agent-sdk/provider-factory
Oct 19, 2026
Merged

dodgeblaster merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:agent-sdk/provider-factory

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make the config package build its provider through the agent SDK instead of reaching the raw ACP provider class, so config no longer depends on the ACP layer.

KiroCrewConfig.create_provider_factory constructed kiro_crew.providers.acp.AcpProvider through a narrow accessor module, src/kiro_crew/agent_sdk/acp_provider_class.py, added by the line-cap split of config/loader.py (#20550). That accessor only relocated the config -> providers.acp dependency into the SDK's exempt tree so scripts/check_agent_sdk_boundary.py would stay green; it did not remove it. The dependency is still there, just laundered through one extra module.

Why it matters

The agent SDK boundary RFC (docs/request-for-change/rfc-crew-agent-sdk-boundary.md) makes kiro_crew.agent_sdk the single surface through which the rest of the tree talks to a backend, migrated one consumer at a time. While config reaches the provider class through a passthrough accessor, swapping or hardening the backend still means touching the config layer, and the boundary checker reports a cleanliness the code does not actually have. Removing the accessor and routing construction through a real SDK factory moves config genuinely behind the boundary — one step of the RFC's additive migration.

Not a goal

  • No behaviour change: the provider is constructed with exactly the same arguments; this is a pure boundary refactor.
  • Does not migrate any other consumer off the ACP layer, and does not change the boundary baseline.
  • Does not add a new public SDK API shape beyond the one factory function the issue asks for.

What changed (motivation → approach → change)

  • Root cause: the only thing in create_provider_factory that touches providers.acp is fetching the class and the final AcpProvider(...) call; config owns all the surrounding policy (model, backend, effort, gateway resolution). The accessor returned the class so config could still do the construction itself — the construction, not the class lookup, is the edge.
  • Approach: give the single ACP driver (src/kiro_crew/agent_sdk/drivers/acp.py) a build_acp_provider(**kwargs) factory that owns that one construction, matching the module's existing deferred-import pattern (provider_label, context_provider_of). Config calls it with the values it already resolves.
  • Change: added build_acp_provider; create_provider_factory now calls it instead of acp_provider_class(); deleted agent_sdk/acp_provider_class.py. The class is still read at call time (function-local import), so a patch of kiro_crew.providers.acp.AcpProvider reaches the factory and the import cycle (providers.acp → acp.client → session → config.loader) stays broken. check_agent_sdk_boundary.py shows no config -> providers.acp edge and the baseline is unchanged (both the old accessor and the driver live in the exempt agent_sdk/ tree).

Backwards compatibility

Compatible: no public signature changes; create_provider_factory returns the same callable building the same AcpProvider with identical arguments.

This diff deletes the private helper agent_sdk/acp_provider_class.py::acp_provider_class(). Grepped origin/main for acp_provider_class across every entry point (chat, cron, subagent, app bundles, crew page, release branch) — it has exactly two readers, both updated in this PR and neither reachable except through the config provider factory, whose behaviour is unchanged:

Reader: src/kiro_crew/config/loader_config.py:create_provider_factory -- chat -- rewritten in this PR to call agent_sdk.drivers.acp.build_acp_provider, which performs the identical construction; the one provider factory used by chat, cron, subagent and crew-page sessions.
Reader: test/test_loader_owners_contract.py:test_a_patched_provider_class_reaches_the_factory -- release -- rewritten in this PR to exercise build_acp_provider and keep pinning the patchability and single-build contract.

Tests

  • test/test_loader_owners_contract.py updated to exercise build_acp_provider and keep pinning the patchability + single-build contract (a patch of providers.acp.AcpProvider reaches both the SDK factory and the config factory). The suite's test_no_loader_module_imports_the_acp_layer still passes.
  • test/test_agent_sdk_provider_identity.py::test_importing_this_module_does_not_load_the_acp_package still passes: the added SDK import is function-local, so loading the SDK does not load kiro_crew.acp.

Manual verification

N/A — unit coverage sufficient. Verified locally: scripts/check_agent_sdk_boundary.py and --test pass; test/test_loader_owners_contract.py, test/test_agent_sdk_provider_identity.py, test/test_acp_provider.py, test/test_cc_permission_mode_seed.py, test/test_crew_reasoning_effort.py pass; black / isort / flake8 / mypy clean on the changed files. Only new/changed and referencing tests were run locally; CI runs the full cross-surface set.

CI note (not this PR): Frontend Tests (2), Real Adapter Contract Tests, the test/test_extras.py::test_requirements_match_setup_cfg[teams] case in a Backend Tests shard (PyJWT[crypto]==2.13.0 vs 2.15.0), and E2E (stub ACP backend, offline) all fail independent of this change. This diff is Python-only in config/agent_sdk and touches no frontend, JS bundle, dependency pin, or dashboard UI. The first three fail byte-identically on unrelated open PRs (an in-flight main fix exists for the PyJWT extras pin). The E2E red is the test_dashboard_playwright_suite harness, not the ACP path: in this run the provider-exercising smoke tests (test_chat_send_receives_reply, test_chat_tool_call_renders) PASSED, and the only failure is the Playwright dashboard suite (gateway timeout / a flaky embed-popout spec — the same test fails on unrelated PRs). A Backend Tests shard hits test/test_session_allocation_bindings.py::...@tree_scan_session_allocation_bindings - Failed: Timeout >120.0s. This is an inherently slow AST tree-scan test (it parses the whole source corpus; facade = kiro_crew.session_allocation, which this diff does not touch). Measured in isolation (-p no:randomly -n 0, same interpreter/venv): 84.7s on this branch vs 85.0s on origin/main — identical, so the diff does not slow the scan; it is a CI-load timeout against the 120s ceiling (the single run on each unrelated PR happened to land under the ceiling). Not rerun again. Coverage Gate fails closed downstream of the test reds (it reports backend-test=failure/frontend-test=failure) and fails the same way on unrelated PRs #21552/#21551/#21549; PR Readiness is downstream of the same reds. No code rerun requested; these clear when main / the flakes do.

Related Issues

Fixes #21468

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

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 17, 2026
@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision cfad00d57fa4060019793ec41c29e7d90832792b touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🟡 CONCERNS

Premise-level review of cfad00d57fa4060019793ec41c29e7d90832792b via the fork AI-review pipeline — 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/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

build_acp_provider copies all 25 AcpProvider.__init__ keywords and their defaults. That is a second constructor signature to keep in sync, and config's edge to the ACP layer stays the same width.

Not justified as shipped

  • Item 2 — duplicate of src/kiro_crew/providers/acp.py:138 (AcpProvider.__init__): the description calls the old accessor "laundered through one extra module", and the new function is also a pure pass-through: one call site (loader_config.py) and 25 of 25 keywords forwarded unchanged. It also re-declares every default (sandbox_mode="auto", memory_mode="persistent", …). If a default changes in AcpProvider, this wrapper's copy overrides it without any error. The description promises build_acp_provider(**kwargs) but the diff ships the full mirrored signature.
    Subtraction: delete the copied defaults from build_acp_provider and make every parameter required-keyword, so AcpProvider stays the only place a default is decided. Config already passes every argument.
    Clears when: the wrapper declares no default that AcpProvider.__init__ also declares, or the author shows a consumer that relies on the wrapper's defaults.

What this change ships

Inventory (6 items) — 5 justified

Intent: keep the config layer from reaching the raw ACP provider class, as a step in the SDK-boundary migration (#21468). This is a refactor (ADDITION-free FIX of a boundary).

  1. Config builds sessions through an SDK factory instead of a class accessor — justified
  2. New exported build_acp_provider copies the constructor's 25 keywords and defaults — duplicate of AcpProvider.__init__
  3. agent_sdk/acp_provider_class.py accessor deleted — justified
  4. Config factory's -> AcpProvider annotation dropped — justified
  5. Config spec and RFC prose repointed to the new function — justified
  6. Patchability contract test rewritten to cover the SDK factory — justified

[FIRST-PRINCIPLES-REVIEWED] cfad00d

Description read

[DESCRIPTION-READ] 0258690c8a0d1a6369532d3d4b0c52de8ad9b4b956dfdf634bcdda929ca42013

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 Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — 🟡 CONCERNS

Design-level review of cfad00d57fa4060019793ec41c29e7d90832792b via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

build_acp_provider keeps a second copy of AcpProvider.__init__'s 25 defaults, so a default changed in only one place silently loses.

Watch

  • Two sets of defaults. The new factory fills in its own defaults (effort_defaults: object = None, member_context: bool = False, memory_mode: str = "persistent", and so on) and then always passes all of them to AcpProvider(...). The config factory never passes effort_defaults, member_context or memory_mode, so those three always come from the driver's copy. If someone changes one of those defaults in providers/acp.py, config sessions keep the old value and nothing fails. mypy also misses a new constructor parameter that the driver never forwards: no caller can set it, and no error is raised. The docstring says the explicit keywords make "parameter drift break here, in CI", but that only holds for renamed or removed parameters, not for changed defaults or added ones.
    Clears when: the driver forwards only the keywords the caller actually passed, so AcpProvider stays the only place defaults live (for example a TYPE_CHECKING-typed **kwargs passthrough, or a sentinel that drops unset values). The other fix is a test asserting that the driver's signature defaults equal inspect.signature(AcpProvider.__init__).

Suggestions

  • The description says the factory is build_acp_provider(**kwargs), but the diff spells out every keyword. Fix the description so reviewers see the actual design choice.

[DESIGN-REVIEWED] cfad00d

Description read

[DESCRIPTION-READ] 510cf22749e6ffb0cb8693cbcadd18093ab9cfc6ee0654fcfb15fa1869cbd247

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 Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed cfad00d57fa4060019793ec41c29e7d90832792b via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] cfad00d

@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed cfad00d57fa4060019793ec41c29e7d90832792b via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] cfad00d

@chenmingwei23
chenmingwei23 force-pushed the agent-sdk/provider-factory branch from c3c426f to 91c39a8 Compare October 17, 2026 08:50
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Addressed in 91c39a8e4fd9fa49886c9a57cd9d73e2808d30da:

  • Lost type check (Design Review): build_acp_provider now declares the full keyword signature mirroring AcpProvider.__init__ instead of **kwargs: Any, and create_provider_factory's inner _acp return is inferred from it rather than annotated object. mypy again checks every keyword of the construction at the config call site — a renamed or removed AcpProvider parameter now fails in CI, not at the first session start. (Verified: adding a bogus keyword to the call makes mypy raise [call-arg].) The driver is the one tree the boundary gate lets name AcpProvider, so this keeps config boundary-clean.
  • Stale spec (Design Review): docs/system-specs/modules/config.md and docs/request-for-change/rfc-crew-agent-sdk-boundary.md now name agent_sdk.drivers.acp.build_acp_provider instead of the deleted agent_sdk.acp_provider_class, in the same commit as the code.
  • "Still a passthrough" (First Principles): with the typed signature the factory is no longer a bare passthrough — it is the single typed construction site the boundary allows, which is what restores the construction check config gave up. The description's ## Backwards compatibility already records that call-time construction, not the class lookup, is what config gives up here.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 17, 2026
@chenmingwei23
chenmingwei23 marked this pull request as ready for review October 17, 2026 10:28
@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners October 17, 2026 10:28
config.create_provider_factory reached kiro_crew.providers.acp.AcpProvider
through a narrow accessor module (agent_sdk/acp_provider_class.py) that only
relocated the config -> providers.acp dependency into the exempt SDK tree.

Give the ACP driver a build_acp_provider(**kwargs) factory that owns the one
construction touching providers.acp, have config call it with the values it
already resolves, and delete the accessor. The class is still read at call
time, so a patch of providers.acp.AcpProvider reaches the factory.

No behaviour change.
@chenmingwei23
chenmingwei23 force-pushed the agent-sdk/provider-factory branch from 91c39a8 to cfad00d Compare October 18, 2026 13:13
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 18, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at cfad00d.

The refactor itself looks sound: config now builds the provider through agent_sdk.drivers.acp.build_acp_provider, the class is still imported at call time, and the defaults match AcpProvider.init today. CI on this head is green.

What blocks approval: the Design and First Principles CONCERNS on this head have no reply. Both point out that build_acp_provider copies all 25 constructor defaults (

def build_acp_provider(
), so if a default changes only in providers/acp.py, config sessions keep the old value without any error. The earlier reply was written for 91c39a8 and covers the typed signature, not the copied defaults.

To clear: either drop the defaults (make the parameters required-keyword, or forward only the arguments the caller passed), or add a test that pins the wrapper's defaults to inspect.signature(AcpProvider.init). Then post a disposition for each lane and fix the description, which still says build_acp_provider(**kwargs).

— crew-pr-reviewer (r111)

@dodgeblaster
dodgeblaster merged commit 0d67a6d into kirodotdev:main Oct 19, 2026
101 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

agent_sdk: build providers through an agent_sdk factory instead of config reading the raw AcpProvider class

3 participants