Summary

Describe the problem and fix in 2–5 bullets:

• Problem: Gateway clients have no supported artifact RPC surface, so SDK/app clients must scrape chat history and infer downloadable media themselves.
• Why it matters: External app clients need stable artifact discovery and download semantics for generated or attached media without depending on transcript internals.
• What changed: Added artifacts.list, artifacts.get, and artifacts.download gateway RPCs over session transcript artifact blocks, with protocol schemas, method discovery, read-scope authorization, and typed unsupported/not-found errors.
• What did NOT change (scope boundary): This does not add a new artifact store or expose arbitrary local file paths; unsupported artifact sources return explicit unsupported errors.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Gateway RPC: add SDK-facing artifacts APIs #74706
• Related SDK: stabilize app-client happy path for agents, sessions, runs #74704
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: Artifacts existed only as transcript content blocks, with no supported gateway RPC projection for SDK/app clients.
• Missing detection / guardrail: There was no focused gateway test asserting artifact list/get/download behavior or typed missing/unsupported errors.
• Contributing context (if known): The SDK happy path needs artifact access without requiring clients to parse chat history payload details.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/server-methods/artifacts.test.ts
• Scenario the test should lock in: Session transcript media blocks are listed as stable artifact summaries, can be fetched by ID, can be downloaded as base64 bytes, and missing/unsupported query paths return typed errors.
• Why this is the smallest reliable guardrail: The new behavior is a gateway RPC projection over existing transcript state, so handler-level tests cover the API contract directly.
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: N/A

User-visible / Behavior Changes

SDK and app clients can call artifacts.list, artifacts.get, and artifacts.download with sessionKey, runId, or taskId query context. Inline transcript artifacts download as base64 bytes; URL-backed artifacts return a URL; unsupported sources return a typed error.

Diagram (if applicable)

Before:
SDK client -> chat.history -> parse transcript media internals

After:
SDK client -> artifacts.list/get/download -> normalized artifact contract

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (Yes)
• If any Yes, explain risk + mitigation: Artifact RPCs expose only artifacts already present in authorized chat/session transcript data and are gated by existing operator.read scope. They do not read arbitrary local file paths.

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node 22.14.0, pnpm
• Model/provider: N/A
• Integration/channel (if any): Gateway RPC
• Relevant config (redacted): Default test config

Steps

1. Seed a session transcript message with an image/file content block.
2. Call artifacts.list with the session key.
3. Call artifacts.get and artifacts.download with the returned artifact ID.
4. Call with missing/unknown artifact context.

Expected

• Artifact summaries are stable and omit raw bytes.
• artifacts.download returns base64 bytes or URL depending on source.
• Missing/unsupported cases return typed errors.

Actual

• Matches expected after this PR.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: artifacts.list, artifacts.get, artifacts.download, runId-to-session lookup, missing query scope, missing artifact ID, protocol schema compilation, method-scope discovery.
• Edge cases checked: Inline base64 artifact bytes are omitted from summaries and returned only from download.
• What you did not verify: A live SDK/OpenMeow client against a running gateway.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: The first artifact source is intentionally conservative and may return artifact_download_unsupported for transcript blocks that reference local-only paths.
  • Mitigation: This avoids exposing arbitrary local filesystem paths while establishing the stable RPC contract for inline and URL-backed artifacts.