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

[zanetworker]

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.