Skip to content

docs(spec): worker handoff for the official CAO AG-UI integration - #6

Closed
plauzy wants to merge 7 commits into
mainfrom
spec/cao-agui-handoff
Closed

plauzy wants to merge 7 commits into
mainfrom
spec/cao-agui-handoff

Conversation

@plauzy

@plauzy plauzy commented Jul 23, 2026 •

Copy link
Copy Markdown
Owner

This pull request was created by @kiro-agent on behalf of @plauzy 👻

Comment with /kiro fix to address specific feedback or /kiro all to address everything.
Learn about Kiro Web


Summary

Adds a single, self-contained worker handoff for a local Kiro agent taking over the official CLI Agent Orchestrator (CAO) AG-UI Dojo integration. Planning/handoff artifact only — no integration code changes.

New file: .kiro/specs/cli-agent-orchestrator-integration/handoff.md, alongside the existing spec (requirements.md / design.md / tasks.md). It consolidates:

  • The conviction — the five differentiators (real-process runtime; one stream over N heterogeneous CLIs; permission prompts as standard interrupts; a construct programming model, not an adapter; privacy-bounded observability) and the abstraction thesis: normalize over N runtimes without coupling to their low-level implementations, with shift-left + dogfooding as the mechanism (not ceremony).
  • A ready-to-paste worker prompt — with the AG-UI roadmap-alignment mapping folded in verbatim and an honesty guardrail (every roadmap row must link a verifiable artifact, not aspirational prose).
  • A maintainer-facing PR lede — TL;DR, opening paragraph, and the interrupt pull-quote, with lede guardrails.

Grounding

Pinned to awslabs/cli-agent-orchestrator@2fcc3efa6c6e70039e5b9a7308ee67cd1f024885 (CAO v2.5.0); canonical URLs only. Ultimately supports closing ag-ui-protocol/ag-ui#2215 / reconciling #2216 — both still open upstream.

Fork history: this spec is #6. Its predecessors #4 (earlier spec) and #5 (implementation, branch feat/cao-agui-integration) are both closed; the implementation branch still exists on the fork.

Pin refresh — edf61cad → 2fcc3efa

The pin previously sat at edf61cad (2026-07-22, CAO v2.3.0 — the original AG-UI Phase 2 commit), which had fallen 151 commits behind upstream. It now points at 2fcc3efa (2026-09-20, CAO v2.5.0), which was awslabs/cli-agent-orchestrator main at time of refresh.

Because the spec carries an explicit determinism rule (claims resolve against the pin, never a moving branch tip), the pin was not bumped blindly — every contract claim was re-verified against the new commit first, and the evidence is recorded as a Pin refresh audit section in requirements.md. Headline findings:

  • docs/agui.md is byte-identical between the two pins, so the two-plane model, replay contract, generative-UI safety model, and L2 construct library documentation all still hold verbatim.
  • POST /agui/v1/run, GET /agui/v1/stream, emit_ui, interrupts/{id}/resume, RUN_FINISHED outcome={type:"interrupt"}, STATE_SNAPSHOT + RFC-6902 STATE_DELTA, and the mock_cli provider are all still present.
  • The [agui] extra range is unchanged: ag-ui-protocol>=0.1.19,<0.2.0.
  • Across all 151 commits, exactly one touched the AG-UI area — 62e721e, adding an ordered multi-key approval action to handoff_approval.py for a new provider. Additive and provider-local; the consumed wire surface is untouched and existing providers retain single-action behavior.

No requirement, design decision, or task changed meaning. The only downstream effect is that cli-agent-orchestrator[agui]==<pinned> now resolves to v2.5.0 instead of v2.3.0.

Testing

Docs-only; the diff against main is exactly the four spec files. Verified:

  • No non-canonical CAO URLs; pinned-commit reference present in all four files.
  • New pin confirmed against awslabs/cli-agent-orchestrator directly — compare reports identical to main, so it is a real, non-dangling pin.
  • Cross-references re-checked against GitHub and corrected where stale: #458 is the closed tracking issue and #485 the merged PR (previously conflated as "PRs [Question] Implementing ag-ui with custom agents ag-ui-protocol/ag-ui#485/React Native + CopilotKit + AG-UI ag-ui-protocol/ag-ui#458"); the closed #4/#5 fork PRs are no longer described as live.
  • Branch is synced with the latest main (f08ccf85) via merge — it had been 1,375 commits behind.

kiro-agent and others added 3 commits July 22, 2026 11:48
Grounds the implementing agent in CAO's merged AG-UI Phase 2 surface
(pinned awslabs/cli-agent-orchestrator@edf61cad) to finalize the official
integration PR closing ag-ui-protocol#2215 (supersedes/reconciles ag-ui-protocol#2216).

- requirements.md: pinned sources of truth, verbatim CAO contract, EARS
  requirements, differentiator conviction, shift-left + dogfood requirements
- design.md: thin-projection architecture mirroring integrations/aws-strands,
  keyless mock_cli example server, flagship interrupt round-trip, fail-closed
  test matrix, meta-dogfood evidence
- tasks.md: actionable checklist w/ determinism + canonical-URL verification

Co-authored-by: Pat Lauer <4451274+plauzy@users.noreply.github.com>
… PR lede)

Single self-contained handoff for a local Kiro worker taking over the official
CAO AG-UI Dojo integration:
- the five differentiators + the abstraction thesis and why shift-left/dogfood
  are the mechanism (not ceremony)
- a ready-to-paste worker prompt with the AG-UI roadmap-alignment mapping and an
  honesty guardrail (each row must link a verifiable artifact)
- a maintainer-facing PR lede (TL;DR, opening paragraph, interrupt pull-quote)

Grounded/pinned to awslabs/cli-agent-orchestrator@edf61cad; canonical URLs only.
@github-actions

github-actions Bot commented Jul 23, 2026 •

Copy link
Copy Markdown

Python Preview Packages — Publish Failed

Preview publish failed for commit 16d3db8.
See the workflow run for details.

…andoff

- Section 4: cross-links PR #4 (spec) / #5 (implementation) / #6 (handoff);
  notes the upstream-bound code in #5 stays free of fork PR numbers.
- Section 5: how to execute tasks.md with a heterogeneous CAO fleet
  (supervisor->workers over MCP), gating each task on its fail-closed test,
  answering worker permission prompts through the AG-UI interrupt lifecycle, and
  recording the run via ag-ui-meta-dogfood as PR evidence (dogfood the orchestrator).
plauzy pushed a commit that referenced this pull request Jul 23, 2026
…andoff

- Section 4: cross-links PR #4 (spec) / #5 (implementation) / #6 (handoff);
  notes the upstream-bound code in #5 stays free of fork PR numbers.
- Section 5: how to execute tasks.md with a heterogeneous CAO fleet
  (supervisor->workers over MCP), gating each task on its fail-closed test,
  answering worker permission prompts through the AG-UI interrupt lifecycle, and
  recording the run via ag-ui-meta-dogfood as PR evidence (dogfood the orchestrator).
plauzy pushed a commit that referenced this pull request Jul 30, 2026
…crew

CPK-7718 #7: the five crew-chat helpers moved from crewai.cli.crew_chat
(0.x - 1.14) to crewai.utilities.crew_chat (1.15+); crewai.cli is now a
deprecation shim that no longer re-exports them. Import them via _capabilities,
which probes the new home first and falls back to the old one, so the
crew-serving path works across the whole >=1.0 floor. Verified on 1.0.0
(resolves from crewai.cli.crew_chat) and 1.15.7 (crewai.utilities.crew_chat).

CPK-7718 ag-ui-protocol#10: the crew is deep-copied at ChatWithCrewFlow construction — route
it through safe_deepcopy so the crewai 1.15.x Crew deep-copy bug doesn't crash.

CPK-7718 #6: litellm stays a direct import (declared as a direct dependency).
plauzy pushed a commit that referenced this pull request Jul 30, 2026
…time dep (CPK-7721 review #6)

The bridge imports nothing from crewai-tools (grep -rn crewai_tools is empty),
yet as a hard runtime dependency it dragged in a heavy transitive tree. Move it
to an optional 'tools' extra so 'ag-ui-crewai[tools]' still resolves it for
crew-serving consumers that need it, while the default install drops the
packages unique to crewai-tools (beautifulsoup4, defusedxml, lxml, pymupdf,
python-docx, pytube, soupsieve, youtube-transcript-api).

Re-locked; uv.lock now carries crewai-tools under marker extra == 'tools'.
plauzy pushed a commit that referenced this pull request Aug 18, 2026
plauzy pushed a commit that referenced this pull request Sep 18, 2026
feat(spring-ai): optional MESSAGES_SNAPSHOT of the run's produced conversation
kiro-agent and others added 3 commits September 21, 2026 21:28
Bring the CAO AG-UI integration spec branch up to date with main.

Co-authored-by: plauzy <4451274+plauzy@users.noreply.github.com>
Co-authored-by: Kiro Agent <244629292+kiro-agent@users.noreply.github.com>
Move the pinned awslabs/cli-agent-orchestrator source of truth from
edf61cad (2026-07-22, CAO v2.3.0 — the original AG-UI Phase 2 commit) to
2fcc3efa (2026-09-20, CAO v2.5.0), 151 commits later and identical to
awslabs main at time of refresh.

Every contract claim was re-verified against the new pin before moving
it, and the evidence is recorded as a "Pin refresh audit" section in
requirements.md. Key findings:

- docs/agui.md is byte-identical between the two pins, so the two-plane
  model, replay contract, generative-UI safety model, and L2 construct
  library documentation all still hold verbatim.
- The run plane, ambient stream, emit_ui, interrupt-resume endpoints,
  interrupt outcome shape, STATE_SNAPSHOT/RFC-6902 STATE_DELTA, and the
  mock_cli provider are all still present.
- The [agui] extra range is unchanged (ag-ui-protocol>=0.1.19,<0.2.0).
- The only AG-UI-area change across the 151 commits is 62e721e, which
  adds an ordered multi-key approval action to handoff_approval.py for a
  new provider. Additive and provider-local; the consumed wire surface
  is untouched.

No requirement, design decision, or task changed meaning. The only
downstream effect is that cli-agent-orchestrator[agui]==<pinned> now
resolves to v2.5.0 instead of v2.3.0.

Co-authored-by: plauzy <4451274+plauzy@users.noreply.github.com>
Co-authored-by: Kiro Agent <244629292+kiro-agent@users.noreply.github.com>
Verified every cross-reference in the spec against GitHub and fixed the
ones that no longer hold:

- Fork PRs: #4 was labelled "this spec", but #4 (spec/cao-agui-integration)
  is closed and this spec is now #6 (spec/cao-agui-handoff). Point at #6 and
  keep #4/#5 as explicitly-closed predecessors for provenance.
- The worker prompt and honesty guardrail referred to "PR #5" as the live
  implementation; #5 is closed, so refer to the feat/cao-agui-integration
  branch (which still exists on the fork) instead.
- "PRs ag-ui-protocol#485/ag-ui-protocol#458" was inaccurate: ag-ui-protocol#485 is the merged PR, ag-ui-protocol#458 is the
  closed tracking issue. Attribute each correctly.
- Noted that ag-ui-protocol#2215 and ag-ui-protocol#2216 are both still open
  upstream, which the Closes/supersedes wording depends on.

Left unchanged because still accurate: awslabs PR ag-ui-protocol#436 (merged), issue
ag-ui-protocol#386, and the upstream ag-ui-protocol#2215/ag-ui-protocol#2216 references.

Co-authored-by: plauzy <4451274+plauzy@users.noreply.github.com>
Co-authored-by: Kiro Agent <244629292+kiro-agent@users.noreply.github.com>
@plauzy plauzy closed this Oct 23, 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.

2 participants