docs(rfc): propose SDK consumption entrypoints and file transfer

[zanetworker]

Related: #1044

Summary

RFC 0006 proposing official Python and TypeScript SDKs that make OpenShell consumable as programmable infrastructure for agent platforms and frameworks, plus streaming file transfer RPCs.

Why: Agent platforms (Anthropic Managed Agents, OpenAI Agents SDK, OpenClaw, Cloudflare) all need a secure execution layer. OpenShell has the enforcement (Landlock, seccomp, L4/L7 policy, credential injection, OCSF audit) and the API (54 gRPC RPCs). But only 8 RPCs are wrapped in the Python SDK, there's no TypeScript SDK, no file transfer RPC, and no OIDC auth in the SDK. Every integration must shell out to the CLI binary or build a custom gRPC client.

What this RFC proposes:

• Extend the Python SDK with OIDC auth, provider attach/detach, streaming watch, and file transfer
• Add streaming UploadFile/DownloadFile gRPC RPCs to the gateway (routed via existing RelayStream infrastructure)
• Ship an official TypeScript SDK (for OpenClaw and Node.js frameworks)
• OIDC authentication in both SDKs for cross-namespace K8s deployments

Three sandbox modes covered:

• Mode 1 (entire agent sandboxed): CLI-driven, no SDK needed
• Mode 2 (platform-managed): SDK in your worker, brain on the platform (Anthropic, OpenAI Responses API)
• Mode 3 (framework extension): SDK embedded in the developer's process (OpenAI Agents SDK, OpenClaw)

Five implementation phases with a dependency analysis showing Phase 1 (OIDC + providers) and Phase 2 (file transfer) can run in parallel.

Related Issues

• Extends the Python SDK at python/openshell/sandbox.py
• Builds on PR feat(auth): per-sandbox authentication to gateway #1404 (per-sandbox auth, merged) and PR feat(auth): add OIDC/Keycloak authentication with RBAC and scope-based permissions #935 (OIDC gateway support, merged)
• Coordinates with PR fix(python): raise SandboxError instead of FileNotFoundError or KeyError #1547 (Python SDK fixes, open) and PR build(python): publish manylinux_2_28 wheels for broader glibc compat… #1117 (Python wheels, open)

Changes

• rfc/0006-sdk-and-file-transfer/README.md - Full RFC document
• rfc/0006-sdk-and-file-transfer/sdk-modes.png - Three sandbox modes architecture diagram
• rfc/0006-sdk-and-file-transfer/sdk-phase-deps.{mmd,png} - Phase dependency diagram
• rfc/0006-sdk-and-file-transfer/sdk-file-transfer.png - UploadFile/DownloadFile sequence diagram
• rfc/0006-sdk-and-file-transfer/sdk-anthropic-worker.png - Anthropic Mode 2 end-to-end sequence

Testing

• mise run pre-commit passes
• Markdown lint clean
• All diagrams render correctly

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• RFC follows the rfc/0000-template structure
• RFC number (0006) does not conflict with existing or in-flight RFCs

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[derekwaynecarr]

can you clarify what is meant by cross namespace deployments?

[zanetworker]

Good call. "Cross-namespace" is K8s jargon that does not belong here. What I meant: the current Python SDK only supports mTLS, which requires distributing TLS client certificates to every consumer. In a K8s deployment that means copying Secrets across namespaces, but the same friction applies outside K8s — any consumer on a different machine needs those certs.

OIDC removes that distribution problem regardless of deployment model. I will rewrite this section to frame it as "SDK consumers need bearer-token auth so they can connect to any OIDC-enabled gateway without distributing client certificates."

[derekwaynecarr]

I don’t understand what oidc has to do with k8s, agree the sdk needs to work with a server that is oidc auth

[zanetworker]

Agreed — OIDC has nothing to do with K8s specifically. The SDK needs to work with any gateway that has OIDC auth enabled, whether that is on K8s, bare metal, or a managed service. I conflated "the most common deployment where this matters" with "the reason it matters." Will decouple the two in the next revision.

[zanetworker]

Positioning relative to RFC 0005 (#1617) and the Python SDK OIDC PR (#1621)

Three SDK efforts are in flight under #1044. Here is how they relate:

PR	Scope	State
#1617 (RFC 0005, @maxdubrinsky)	Extract openshell-sdk Rust crate, ship @openshell/sdk TypeScript binding via napi-rs, refactor CLI onto SDK	RFC + working prototype
#1621 (@mrunalp)	Add OIDC bearer auth to the existing pure-Python SDK	Code, ready for review
#1590 (this RFC 0006)	Broader SDK roadmap: consumption patterns (Mode 1/2/3), file transfer RPCs, Python SDK surface expansion, platform integration examples (Anthropic, OpenAI, OpenClaw)	RFC, no code

RFC 0005 and RFC 0006 are complementary, not competing. RFC 0005 delivers the shared Rust core and TypeScript binding — the "how" for the TS half. This RFC frames the "why" and "what" across both languages: which consumption patterns platforms need, what RPC gaps block adoption (file transfer), and how the SDK surface maps to real platform integrations.

Concretely, this RFC covers areas that RFC 0005 explicitly defers or does not address:

• File transfer RPCs (UploadFile/DownloadFile): gateway proto changes, streaming design, routing via ConnectSupervisor/RelayStream
• Python SDK surface expansion: provider attach/detach, watch, policy, services (wrapping existing RPCs, not rebuilding transport)
• Platform consumption patterns: Anthropic Managed Agents (Mode 2), OpenAI Agents SDK (Mode 3), OpenClaw, CI/CD
• Python-on-shared-core migration path: RFC 0005 defers this as a non-goal; this RFC scopes it as a future phase

The intended reading order: this RFC for the overall SDK strategy and surface area, RFC 0005 for the shared core architecture and TS binding implementation.

Will update the RFC text to reference RFC 0005 directly and to decouple OIDC from K8s framing per @derekwaynecarr feedback.