feat(agent): opt-in output_file declares session deliverables

[duyet]

Closes #341 (part of #347). Coordinates with #340 on the Artifacts panel conceptually; this PR is the tool/declaration side only.

What

output_file is no longer a default-on write to /mnt/session/outputs/. It is an opt-in tool (same configs gate as browser / run_dynamic_worker) that marks a file as a session deliverable:

{
  "type": "agent_toolset_20260401",
  "configs": [{ "name": "output_file", "enabled": true }]
}

• Schema: { path, description?, media_type?, data? } (legacy filename + content still writes under /mnt/session/outputs/)
• Successful calls emit agent.output_declared (OMA extension, not in model context)
• GET /v1/sessions/:id overlays outputs[] from the event log at read time — no new table
• Console conversation view: compact deliverable card, not raw JSON
• Inspector Artifacts tab: ★ Declared output badge + agent description as subtitle
• Multiple declarations per turn are independent
• data is inline base64 (no sandbox write required); path is a best-effort sandbox cross-ref

Out of scope

• Full Console: Artifacts panel in session detail #340 artifacts panel (tool results / sandbox listing / uploads / lightbox)
• Strict existence validation, versioning, external destinations
• CLI rewrite / SDK event union
• Issues chore: release main #358 / chore: version packages #400

Why a tool, emitted from the harness

The agent already acts through tools, so output_file participates in the tool loop, turn history, and hooks. The declaration event is broadcast after agent.tool_result (same pattern as call_agent_* thread events) so inline data can live on the event without stuffing base64 into the model-facing result.

Test plan

• output_file omitted by default; registered when configs opt in
• path-only declare succeeds when the sandbox file is missing
• data writes bytes best-effort and does not echo in the tool result
• agent.output_declared is skipped by eventsToMessages (prompt-cache)
• GET /v1/sessions/:id includes outputs[]
• Console deliverable card + Artifacts tab tests
• pnpm typecheck && pnpm test
• verify-oma: landing + console-login (no secrets)

Could not browser-verify the Artifacts tab or conversation card in a live authenticated session (login needs secrets this run did not invent). Unit tests cover those UIs.

  

Summary by Sourcery

Enable agents to explicitly declare session deliverables and surface them consistently across the event log, session API, and Console.

New Features:

• Add an opt-in output_file tool for declaring session deliverables with metadata and optional inline base64 content.
• Expose declared deliverables through session APIs and add Console conversation cards and an Inspector Artifacts tab.

Bug Fixes:

• Prevent declared output events and inline payloads from entering model-facing conversation history.

Enhancements:

• Derive session outputs[] from the event log without introducing a new persistence table.
• Preserve legacy filename/content output writes while allowing path-only declarations and best-effort sandbox metadata.

Documentation:

• Update tool, architecture, self-hosting, and product documentation to describe opt-in deliverable declarations.

Tests:

• Add coverage for opt-in registration, declaration handling, event projection, API responses, model-history exclusion, and Console rendering.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 50336865-3fc5-4eb1-89db-4fa32fd6c459

---

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

[sourcery-ai]

Reviewer's Guide

Converts output_file from a default persistence tool into an opt-in deliverable declaration workflow: the harness emits model-context-excluded events, session APIs derive outputs[] from the event log, and the console presents declarations as compact cards and an Artifacts tab while retaining legacy filename/content writes.

Sequence diagram for declaring a session deliverable

sequenceDiagram
    participant Agent
    participant Harness
    participant OutputFile as output_file
    participant EventLog
    participant SessionAPI
    participant Console

    Agent->>Harness: call output_file(path, description, media_type, data)
    Harness->>OutputFile: executeOutputFile(sandbox, args)
    OutputFile-->>Harness: JSON result without inline data
    Harness->>EventLog: emit agent.output_declared
    Note over EventLog: Excluded from model context
    SessionAPI->>EventLog: read session events
    EventLog-->>SessionAPI: agent.output_declared events
    SessionAPI-->>Console: outputs[] without data

Loading

File-Level Changes

Change	Details	Files
Make output_file an opt-in deliverable declaration tool with backward-compatible legacy writes.	Remove it from default registration and enable it through the toolset configs gate. Support sandbox path declarations, optional metadata, inline base64 data, best-effort writes/statistics, and legacy filename plus content. Add execution coverage for registration, declaration modes, failures, metadata, and independent calls.	apps/agent/src/harness/tools.ts apps/agent/src/harness/output-file-tool.test.ts AGENTS.md docs/tools.md docs/self-host.md docs/architecture-overview.md
Emit and model agent.output_declared as an observational event carrying deliverable metadata and optional inline payload.	Recover original tool-call input across the tool loop and broadcast the declaration after the matching tool result. Suppress declaration events from model history while preserving payloads in the event log. Project valid declarations into read-time session outputs[] entries without exposing base64 data.	apps/agent/src/harness/default-loop.ts apps/agent/src/harness/output-declared.ts apps/agent/src/harness/output-declared.test.ts packages/api-types/src/types.ts packages/api-types/src/declared-outputs.ts packages/api-types/src/declared-outputs.test.ts test/unit/history-conversion.test.ts
Expose declared outputs through session status APIs and both runtime implementations.	Derive outputs from Durable Object and Node event histories without adding persistence tables. Overlay outputs: [] safely when live runtime data is unavailable. Add API and projection tests covering ordering, malformed events, payload stripping, and fallback behavior.	apps/agent/src/runtime/session-do.ts apps/main-node/src/lib/node-session-router.ts packages/session-runtime/src/router.ts packages/http-routes/src/sessions/index.ts packages/http-routes/src/sessions/declared-outputs.test.ts apps/console/src/types/session.ts
Add console presentation for declared deliverables in conversation and Inspector Artifacts.	Render output-file calls as compact cards with filename, description, size, MIME metadata, timestamp, and error state instead of raw JSON. Add the Artifacts inspector tab with badges, descriptions, metadata, and an empty state. Add opt-in tool selection to the agent configuration UI and component tests.	apps/console/src/components/ai-elements/tool-renderers.tsx apps/console/src/components/ai-elements/tool-renderers.test.tsx apps/console/src/pages/SessionDetail.tsx apps/console/src/pages/session-detail/Inspector.tsx apps/console/src/pages/session-detail/Inspector.artifacts.test.tsx apps/console/src/pages/agents/AgentFormDialog.tsx
Update product and developer documentation to describe deliverable declarations and distinguish them from persisted session files.	Document opt-in configuration, event semantics, legacy compatibility, and the separation between declared outputs and the Files panel. Update public feature and architecture descriptions to remove the default-on output-file behavior.	apps/web/src/components/BuildingBlocks.astro apps/web/src/components/FeaturesSection.astro apps/web/src/pages/open-tag.astro

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#341	Add an opt-in output_file built-in tool that supports path-based and inline base64 declarations, best-effort sandbox metadata, and multiple independent declarations.	✅
#341	Emit and persist an agent.output_declared event for successful declarations, exclude it from model history, and derive outputs[] from those events in GET /v1/sessions/:id.	✅
#341	Render declared outputs distinctly in the Console conversation and Inspector Artifacts tab, including the declared-output badge and agent-provided description.	✅

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Sorry @duyet, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 15 hours by commenting @sourcery-ai review. Upgrade to get a review now.