Skip to content

feat(gateway): add artifact RPCs#74898

Closed
tmimmanuel wants to merge 2 commits intoopenclaw:mainfrom
tmimmanuel:fix/74769-artifact-rpcs
Closed

feat(gateway): add artifact RPCs#74898
tmimmanuel wants to merge 2 commits intoopenclaw:mainfrom
tmimmanuel:fix/74769-artifact-rpcs

Conversation

@tmimmanuel
Copy link
Copy Markdown
Contributor

@tmimmanuel tmimmanuel commented Apr 30, 2026

Summary

  • Problem: @openclaw/sdk has artifact helpers, but Gateway did not expose SDK-facing artifact ledger/download RPCs.
  • Why it matters: App SDK clients need a stable way to list, inspect, and download artifacts produced in session transcripts without scraping internal transcript formats.
  • What changed: Added artifacts.list, artifacts.get, and artifacts.download Gateway RPCs, protocol schemas/types, method discovery/scopes, handler tests, and generated Swift protocol models.
  • What did NOT change (scope boundary): This does not add persistent binary artifact storage or new artifact production paths; it exposes artifacts already present in session transcript content blocks.

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

Root Cause (if applicable)

  • Root cause: Gateway session transcripts already carried inline artifact-like content, but there was no public RPC contract for SDK clients to discover or retrieve those artifacts.
  • Missing detection / guardrail: SDK and Gateway tests did not cover artifact RPC availability or protocol generation for artifact contracts.
  • Contributing context (if known): The OpenMeow SDK gap map identifies artifact list/get/download as required app-client basics.

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 and protocol generation checks.
  • Scenario the test should lock in: list/get/download artifact summaries from transcript content, runId session lookup, typed not-found/query errors, method scopes, and generated protocol models.
  • Why this is the smallest reliable guardrail: It exercises the Gateway handler/protocol seam without requiring a live model run to produce artifacts.
  • Existing test that already covers this (if any): N/A.
  • If no new test is added, why not: N/A.

User-visible / Behavior Changes

Gateway now advertises and handles artifacts.list, artifacts.get, and artifacts.download for session/run/task-scoped artifact discovery and retrieval.

Diagram (if applicable)

Before:
[external app] -> [artifact helper] -> [unsupported / no Gateway RPC]

After:
[external app] -> [artifacts.* RPC] -> [session transcript content blocks] -> [artifact summary/download]

Security Impact (required)

  • New permissions/capabilities? (Yes/No) Yes
  • Secrets/tokens handling changed? (Yes/No) No
  • New/changed network calls? (Yes/No) No
  • Command/tool execution surface changed? (Yes/No) No
  • Data access scope changed? (Yes/No) Yes
  • If any Yes, explain risk + mitigation: Artifact read/download methods require operator.read and only expose artifacts discoverable from existing session transcript content for the requested session/run/task scope.

Repro + Verification

Environment

  • OS: Ubuntu/Linux local workspace
  • Runtime/container: Node 22.22.0 via nvm, pnpm 10.33.2
  • Model/provider: N/A
  • Integration/channel (if any): Gateway RPC / SDK artifact surface
  • Relevant config (redacted): N/A

Steps

  1. On current main, attempt to use Gateway artifact list/get/download RPCs.
  2. Observe that no SDK-facing Gateway artifact RPC handlers exist.
  3. Apply this PR.
  4. Query artifacts for a session transcript containing inline image/file content.

Expected

  • Gateway returns artifact summaries and download payloads, or typed query/not-found errors.

Actual

  • Before this PR, the artifact RPCs were not available.

Evidence

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

Local verification:

  • pnpm protocol:check
  • pnpm tsgo:prod
  • pnpm check:test-types
  • pnpm lint --threads=8
  • node scripts/test-projects.mjs src/gateway/server-methods/artifacts.test.ts
  • OPENCLAW_OPENGREP_BASE_REF=upstream/main...HEAD scripts/run-opengrep.sh --changed --json --error

Human Verification (required)

  • Verified scenarios: replayed the artifact RPC implementation onto current upstream/main, pushed once before local tests per request, then fixed generated protocol output, schema validation, test fixture types, and lint issues.
  • Edge cases checked: missing query scope, missing artifact id, runId-to-session lookup, inline base64 download, generated Swift protocol models, and OpenGrep changed-path scan.
  • What you did not verify: did not run a live Gateway/model session that produces artifacts.

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.

Compatibility / Migration

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

Risks and Mitigations

  • Risk: Transcript-derived artifact discovery may not cover every future artifact storage backend.
    • Mitigation: The RPC response includes source/download metadata and keeps storage-specific behavior behind the Gateway handler.

@openclaw-barnacle openclaw-barnacle Bot added app: macos App: macos app: web-ui App: web-ui gateway Gateway runtime size: XL labels Apr 30, 2026
@clawsweeper
Copy link
Copy Markdown
Contributor

clawsweeper Bot commented Apr 30, 2026 •
edited
Loading

Thanks for the context here. I swept through the related work, and this is now duplicate or superseded.

Close as superseded. This PR is useful source work, but it has unresolved artifact scoping and download-source issues, and the open maintainer hardening PR #74926 contains this PR's exact commits plus the follow-up fixes, SDK wiring, docs, tests, and changelog coverage needed for the linked artifact API request.

So I’m closing this here and keeping the remaining discussion on the canonical linked item.

Review details

Best possible solution:

Use #74926 as the canonical path: preserve credit for this source contribution, review the maintainer hardening branch, and let #74706 close only after the hardened Gateway/SDK/docs implementation lands.

Do we have a high-confidence way to reproduce the issue?

Yes. A source-level reproduction is clear: current main lacks artifacts.*, and this PR's collectArtifactsFromMessages can return untagged same-session artifacts for a runId or taskId query because current transcript metadata only carries id/seq.

Is this the best way to solve the issue?

No for this PR as written. The safer solution is the open #74926 superset, which requires explicit provenance for run/task-scoped artifacts, rejects unsafe/local URL downloads, and wires the App SDK/docs surface.

Security review:

Security review needs attention: The diff adds a read/download artifact surface with concrete data-scoping and URL-source policy issues; the open maintainer superseding PR tracks the hardening.

  • [medium] Run-scoped queries include untagged transcript blocks — src/gateway/server-methods/artifacts.ts:211
    Because ordinary transcript messages do not reliably carry run/task metadata, runId and taskId queries can expose unrelated same-session artifacts through a narrower API response.
    Confidence: 0.88
  • [medium] Validate artifact URL download sources — src/gateway/server-methods/artifacts.ts:127
    The handler returns arbitrary non-data url, openUrl, or source.url values as downloadable URLs without scheme or trusted Gateway path checks, which can hand unsafe local or unsupported sources to clients.
    Confidence: 0.8

What I checked:

Likely related people:

  • steipete: GitHub commit history for packages/sdk/src/client.ts shows feat: add OpenClaw SDK package introduced the SDK package and artifact placeholder/types later touched by this PR's goal. (role: introduced App SDK artifact surface; confidence: high; commits: 43f6c8b01aa7, 204d200be3f9, 29de89a8d98c; files: packages/sdk/src/client.ts, packages/sdk/src/types.ts, packages/sdk/src/index.test.ts)
  • shakkernerd: GitHub commit history for Gateway method discovery and scope files points to prior Gateway RPC/method-surface work in the same registration and authorization area touched by this PR. (role: adjacent Gateway RPC wiring maintainer; confidence: medium; commits: 4109446c2f54; files: src/gateway/server-methods-list.ts, src/gateway/method-scopes.ts, src/gateway/server-methods.ts)
  • BunsDev: BunsDev opened the active maintainer hardening PR that includes this PR's commits and adds the missing provenance, source-policy, SDK, docs, and validation follow-through. (role: maintainer follow-up owner; confidence: high; commits: 2792bdd09035, d4d64cdf5da8, 1ac5dec86719; files: src/gateway/server-methods/artifacts.ts, src/gateway/server-methods/artifacts.test.ts, packages/sdk/src/client.ts)
  • bitloi: GitHub path history shows recent SDK client/test stabilization work adjacent to the unsupported artifact namespace and SDK helper follow-through. (role: recent SDK maintainer; confidence: medium; commits: e6abd9e3d8c4; files: packages/sdk/src/client.ts, packages/sdk/src/index.test.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 914287642de5.

@clawsweeper clawsweeper Bot mentioned this pull request Apr 30, 2026
Closed
25 tasks
@BunsDev BunsDev mentioned this pull request Apr 30, 2026
Merged
@clawsweeper clawsweeper Bot closed this Apr 30, 2026
BunsDev added a commit that referenced this pull request May 1, 2026
@BunsDev
fix(gateway): harden artifact RPCs
a102f4d 
Add Gateway artifact RPCs and SDK helpers for list/get/download, with transcript provenance checks, safer download source handling, task/run/session coverage, generated protocol models, docs, and the refreshed generated config schema baseline.

Closes #74706.
Refs #74898, #74769, #74804, #74786.
@clawsweeper clawsweeper Bot mentioned this pull request May 2, 2026
Open
6 tasks
lxe pushed a commit to lxe/openclaw that referenced this pull request May 6, 2026
@BunsDev @lxe
fix(gateway): harden artifact RPCs
e81e6ba 
Add Gateway artifact RPCs and SDK helpers for list/get/download, with transcript provenance checks, safer download source handling, task/run/session coverage, generated protocol models, docs, and the refreshed generated config schema baseline.

Closes openclaw#74706.
Refs openclaw#74898, openclaw#74769, openclaw#74804, openclaw#74786.
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 9, 2026
@BunsDev
fix(gateway): harden artifact RPCs
1c29d70 
Add Gateway artifact RPCs and SDK helpers for list/get/download, with transcript provenance checks, safer download source handling, task/run/session coverage, generated protocol models, docs, and the refreshed generated config schema baseline.

Closes openclaw#74706.
Refs openclaw#74898, openclaw#74769, openclaw#74804, openclaw#74786.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

app: macos App: macos app: web-ui App: web-ui gateway Gateway runtime size: XL

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Gateway RPC: add SDK-facing artifacts APIs

1 participant

@tmimmanuel