[delete-cloud]

Summary

• add ADR-0027 for AgentKit session result and artifact reference models
• define what can move down to agentkit: result models, reducers, artifact refs, metadata-only store protocols
• explicitly keep Git workspaces, publication, Docker retention, HTTP APIs, and CLI behavior in coding_agent

Validation

• grep -n '[[:blank:]]$' coding-agent/docs/adr/0027-agentkit-session-result-and-artifact-references.md
• rg -n 'TODO|TBD|placeholder' coding-agent/docs/adr/0027-agentkit-session-result-and-artifact-references.md
• git diff --check
• uv run python ADR metadata check

Summary by CodeRabbit

• Documentation
  • Added architecture documentation for planned improvements to session result handling and artifact reference management.

[coderabbitai]

Warning

Rate limit exceeded

@delete-cloud has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 51 minutes and 32 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 97382014-8e83-41ff-bb85-b1232e5de9c2

📥 Commits

Reviewing files that changed from the base of the PR and between e3c90f6 and 749676e.

📒 Files selected for processing (1)

• coding-agent/docs/adr/0027-agentkit-session-result-and-artifact-references.md

📝 Walkthrough

Walkthrough

This PR introduces ADR-0027, which documents a planned boundary shift for agent session/turn results and artifact references. The decision moves provider-neutral domain models and reducers into agentkit, while coding_agent retains responsibility for Git/Docker/workspace/HTTP/CLI integration and response adapters. The ADR specifies domain types, storage protocols, implementation phases across four future PRs, and acceptance criteria.

Changes

ADR-0027: agentkit Session Result and Artifact Reference Ownership

Layer / File(s)	Summary
Decision boundary and purpose coding-agent/docs/adr/0027-agentkit-session-result-and-artifact-references.md	Establishes that provider-neutral session/turn result and artifact-reference models/reducers belong in agentkit, driven by TurnTrace, while coding_agent owns all product-specific Git, workspace, HTTP, and CLI behavior.
Domain contracts and boundary constraints coding-agent/docs/adr/0027-agentkit-session-result-and-artifact-references.md	Defines initial agentkit domain types (TurnResult, SessionResult, VerificationSummary, FailureSummary, ArtifactRef, ResultRef), metadata-only artifact-reference storage protocols, and explicit constraints forbidding agentkit from generating artifacts or controlling workspace operations.
Consequences, implementation roadmap, and acceptance coding-agent/docs/adr/0027-agentkit-session-result-and-artifact-references.md	Documents consequences (reusability, continued workspace control, temporary duplication, convergence path), describes a four-PR implementation plan (models, artifact store protocol, endpoint adapter, durable ref mapping), and specifies acceptance criteria for reducer/endpoint/ref/store/tooling behavior with references to related ADRs and source files.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• delete-cloud/Coding-Agent-Loop#90: Both ADR-0016 and ADR-0027 define the ownership boundary between agentkit runtime/contracts and coding_agent integrations; ADR-0027 specifically applies that boundary to session/turn result extraction and artifact-reference handling.

Poem

🐰 A rabbit maps the path ahead,
Where models roam and refs are bred,
Agentkit holds the truth so clear,
While coding-agent stays right here. 🎯

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: add ADR 0027 agentkit result refs' accurately summarizes the main change: adding a new Architecture Decision Record documenting AgentKit result and artifact reference models.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/adr-0027-agentkit-result-artifacts

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

coding-agent/docs/adr/0027-agentkit-session-result-and-artifact-references.md (1)

86-97: ⚡ Quick win

Clarify whether phase outcome types are part of the initial implementation.

Lines 88-92 introduce RunPhase, PhaseStatus, and PhaseOutcome, but these types are not listed in the initial agentkit result surface (lines 33-42). The qualifier "may define" (line 88) suggests these are optional, but this creates scope ambiguity for implementers.

If phase outcomes are part of PR 1 (lines 142-154), add them to the initial surface list. If they are optional or deferred to a later PR, state that explicitly to avoid confusion.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@coding-agent/docs/adr/0027-agentkit-session-result-and-artifact-references.md`
around lines 86 - 97, Clarify whether the phase outcome types are part of the
initial agentkit surface: either add `RunPhase`, `PhaseStatus`, and
`PhaseOutcome` to the initial result surface list (so they appear alongside
other initial types) or explicitly mark them as deferred/optional in the ADR
text; update the paragraph that currently says "may define" to state
definitively which of `RunPhase`, `PhaseStatus`, and `PhaseOutcome` are included
in PR 1 (or that they will be implemented in a follow-up), referencing the type
names `RunPhase`, `PhaseStatus`, and `PhaseOutcome` so readers and implementers
know their intended scope.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@coding-agent/docs/adr/0027-agentkit-session-result-and-artifact-references.md`:
- Around line 33-42: Add a new subsection "Result references" that defines
ResultRef (analogous to ArtifactRef) and specifies its purpose and fields: a
unique id/reference (result_id), result_type or kind (e.g., TurnResult,
SessionResult, VerificationSummary, FailureSummary), origin metadata
(source_turn_id or session_id and timestamp), an optional human-readable
summary/label, and an optional links field to ArtifactRef or ResultRef for
provenance; also explain how ResultRef differs from ArtifactRef (ArtifactRef
points to stored artifacts/binaries, ResultRef points to logical result records)
and show expected usage with reducers like latest_turn_result(...) and
result_from_turn_trace(...).

---

Nitpick comments:
In
`@coding-agent/docs/adr/0027-agentkit-session-result-and-artifact-references.md`:
- Around line 86-97: Clarify whether the phase outcome types are part of the
initial agentkit surface: either add `RunPhase`, `PhaseStatus`, and
`PhaseOutcome` to the initial result surface list (so they appear alongside
other initial types) or explicitly mark them as deferred/optional in the ADR
text; update the paragraph that currently says "may define" to state
definitively which of `RunPhase`, `PhaseStatus`, and `PhaseOutcome` are included
in PR 1 (or that they will be implemented in a follow-up), referencing the type
names `RunPhase`, `PhaseStatus`, and `PhaseOutcome` so readers and implementers
know their intended scope.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8252fd81-dbe5-43d4-a4da-da51d0f3588e

📥 Commits

Reviewing files that changed from the base of the PR and between 45bb82a and e3c90f6.

📒 Files selected for processing (1)

• coding-agent/docs/adr/0027-agentkit-session-result-and-artifact-references.md