ADR-003: Public-read source URL for fetch_oss_file

Status

Accepted

Date

2026-07-30

Context

Controlled SuperAgent traces showed that fetch_oss_file accepts object_uri and filename. An oss:// request failed with public_endpoint_missing, while earlier HTTPS attempts reached file-type handling. The user confirmed that the installed Tool reads a publicly accessible OSS address without a Provider and that the OSS deployment is public-read.

The previous ARR adapter explicitly wrote every object with object ACL private. That overrides a public-read bucket and would make a generated public URL unusable. At the same time, making every processing output public would unnecessarily widen exposure.

Decision

ARR requires the integration bucket to report bucket ACL public-read; anonymous writes remain forbidden.
Only committed/source_xml/source.xml is written with object ACL public-read. Staged objects, generated reports, result JSON and exchange objects remain explicitly private.
arr-opera-daily-program-input-3 includes a required oss.url generated by ARR as https://{bucket}.oss-{region}.aliyuncs.com/{encoded-object-key}. It contains no query signature or secret.
The Main Prompt passes oss.url unchanged as fetch_oss_file.object_uri and the canonical attachment name as filename, exactly once. It must not construct oss://, sign or substitute another URL.
XML extension/MIME acceptance remains a separate platform Tool configuration requirement.

Rationale

ARR owns the bucket, endpoint and immutable object key, so it can generate one deterministic address without asking the Agent to infer storage semantics. Object-level ACL selection satisfies anonymous source download while keeping intermediate and output artifacts private.

Consequences

fetch_oss_file needs no OSS Provider, AccessKey or signed URL for this flow.
A committed source XML is anonymously readable to anyone who has its URL; the URL is not a secret or an authorization mechanism. Retention, access logging and public-source privacy review remain deployment duties.
Readiness now rejects a private bucket for this integration.
Deploying code and Prompt changes does not by itself allow XML; the platform must permit .xml and application/xml if it still returns extension_not_allowed.

Supersedes

The private-object/credential-backed Provider assumption in earlier implementation notes and the historical oss:// Prompt experiment.

arr_processing/source_message.py
arr_storage/aliyun_oss_v2.py
prompts/arr_opera_daily_program_input.schema.json
prompts/arr_opera_daily_main_agent_prompt.md
.project-docs/50-evidence/topics/2026-07-30-superagent-fetch-oss-prompt-experiment.md

2.7 KiB Raw Blame History