feat(sdk-ts): add watchLogs with loss-aware resume

[letv1nnn]

Summary

Add watchLogs to the TypeScript SDK: a loss-aware, resumable stream of a sandbox's log lines and platform events. It reconnects transparently on a transient drop and resumes from the last cursor seen, mirroring the Rust SDK's watch_logs reconnect/backoff/resume contract from #3209.

Related Issue

Refs #3055 (partial, item C of #3209 TODO)

Changes

• SandboxClient.watchLogs(name, options?): reconnecting, cursor-resumable log/event stream. Retries only Unavailable with capped exponential backoff (100ms to 2s, reset per delivered event); OUT_OF_RANGE is terminal and never retried.
• New curated types (LogLine, PlatformEvent, WatchOptions, WatchEvent union) and a new out_of_range SdkErrorCode, exported from index.ts.
• Defaults to followLogs: true when neither follow option is set, so the call can't silently hang forever.
• Docs: new "Watch Logs and Events" section in docs/sdk/typescript.mdx.

Testing

Testing

• mise run pre-commit passes
• Unit tests added/updatedhe call can't silently hang forev
• E2E tests added/updated

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[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.

[johntmyers]

/ok to test 01ddfb6

[github-actions]

Label test:e2e applied for 01ddfb6. Open Branch E2E Checks, find the run for commit 01ddfb6, and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[johntmyers]

gator-agent

PR Review Status

The independent review found no blocking issues in the TypeScript watch helper, reconnect and cursor handling, error mapping, or regression tests. The existing TypeScript SDK docs now explain the new watch API and terminal gap behavior.

Blocking findings: None.

Carried findings: None.

Non-blocking suggestions: None.

The current head has been mirrored for testing. Branch Checks, Helm Lint, and a fresh Branch E2E Checks run are running; Gator will inspect their results before requesting maintainer approval.

Gator metadata

• Validation: Focused TypeScript SDK follow-up to issue #3055 and merged PR #3209.
• Docs: Updated docs/sdk/typescript.mdx; existing navigation is sufficient.
• Checks: Current-head Branch Checks and Helm Lint running; Trivy Changes passed.
• E2E: test:e2e applied and /ok to test posted for the full current head. Fresh current-head run 38299490186 started after the label was applied and passed PR metadata resolution; its version job is running, confirming E2E was selected. The bot's generic rerun guidance is satisfied by this fresh dispatch; an already-running run cannot be rerun.
• Local verification: Dependency installation was denied network access to npm, so no local tests ran. Branch Checks includes the TypeScript SDK CI suite.
• Head SHA: 01ddfb6375cdd6457570c4a6866f823f069ef784
• Base SHA: eef8bec0c96b384556d608f8d899a8a96f5d17a1
• Merge base SHA: eef8bec0c96b384556d608f8d899a8a96f5d17a1
• Patch ID: 8453a056f5df8d69316035c40f9564036b9aba17
• Gator payload: 12
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:watch-pipeline

[johntmyers]

gator-agent

Monitoring Complete

Monitoring is complete because PR #3778 has merged. The prior Gator review found no blocking findings.

I am removing the remaining active gator:approval-needed label because there is nothing left for Gator to monitor on this PR.

Gator metadata

• Head SHA: 01ddfb6375cdd6457570c4a6866f823f069ef784
• Gator payload: 12