opencomputer-sdk 0.5.2__tar.gz → 0.5.4__tar.gz

{opencomputer_sdk-0.5.2 → opencomputer_sdk-0.5.4}/.gitignore

@@ -10,6 +10,10 @@ Thumbs.db
 .idea/
 .vscode/
 
+# Claude Code session state — never check in
+.claude/*.lock
+.claude/settings.local.json
+
 # Environment files
 .env
 .env.*

{opencomputer_sdk-0.5.2 → opencomputer_sdk-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencomputer-sdk
-Version: 0.5.2
+Version: 0.5.4
 Summary: Python SDK for OpenComputer - cloud sandbox platform
 Project-URL: Homepage, https://github.com/diggerhq/opensandbox
 Project-URL: Repository, https://github.com/diggerhq/opensandbox

opencomputer_sdk-0.5.4/examples/stream_demo.py

@@ -0,0 +1,101 @@
+"""stream_demo.py — simulates apt-install-style output over ~6 seconds
+via shell.run(), printing each chunk with its arrival timestamp so you
+can see exactly how streaming feels in practice.
+
+Usage:
+    python sdks/python/examples/stream_demo.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+
+from opencomputer import Sandbox
+
+API_URL = os.environ.get("OPENCOMPUTER_API_URL", "https://app.opencomputer.dev")
+API_KEY = os.environ.get("OPENCOMPUTER_API_KEY", "opensandbox-dev")
+
+# Pseudo-apt output. Uses /bin/echo (external, flushes on exit) rather
+# than bash builtins so glibc block-buffering doesn't hide the streaming.
+APT_SIM = r"""
+/bin/echo "Reading package lists..."
+sleep 0.3
+/bin/echo "Building dependency tree..."
+sleep 0.2
+/bin/echo "Reading state information..."
+sleep 0.4
+/bin/echo "The following NEW packages will be installed:"
+/bin/echo "  libfoo1 libfoo-dev pkg-a pkg-b pkg-c"
+sleep 0.3
+/bin/echo "0 upgraded, 5 newly installed, 0 to remove and 0 not upgraded."
+/bin/echo "Need to get 4,321 kB of archives."
+/bin/echo "After this operation, 12.3 MB of additional disk space will be used."
+sleep 0.4
+for i in 1 2 3 4 5; do
+  /bin/echo "Get:$i http://deb.example.com/debian bookworm/main amd64 pkg-$i"
+  sleep 0.2
+done
+/bin/echo "Fetched 4,321 kB in 1s (4,321 kB/s)"
+sleep 0.3
+for i in 1 2 3 4 5; do
+  /bin/echo "Selecting previously unselected package pkg-$i."
+  /bin/echo "Unpacking pkg-$i (1.0-$i) ..."
+  sleep 0.15
+  /bin/echo "Setting up pkg-$i (1.0-$i) ..."
+  sleep 0.15
+done
+/bin/echo "W: Could not fetch http://example.com/deprecated — ignoring" >&2
+/bin/echo "Processing triggers for libc-bin (2.36-9+deb12u3) ..."
+sleep 0.4
+/bin/echo "Processing triggers for man-db (2.11.2-2) ..."
+sleep 0.5
+/bin/echo "done."
+"""
+
+
+async def main() -> None:
+    print(f"API: {API_URL}")
+    sb = await Sandbox.create(api_url=API_URL, api_key=API_KEY, template="base")
+    print(f"sandbox: {sb.sandbox_id}")
+
+    t0 = time.monotonic()
+    out_count = 0
+    err_count = 0
+    last_t = t0
+
+    try:
+        sh = await sb.exec.shell()
+
+        def on_out(b: bytes) -> None:
+            nonlocal out_count, last_t
+            out_count += 1
+            now = time.monotonic()
+            gap = now - last_t
+            last_t = now
+            # Show dt-since-start and gap-since-last-chunk.
+            print(f"[+{now - t0:5.2f}s Δ{gap:4.2f}s OUT] {b.decode().rstrip()}")
+
+        def on_err(b: bytes) -> None:
+            nonlocal err_count, last_t
+            err_count += 1
+            now = time.monotonic()
+            gap = now - last_t
+            last_t = now
+            print(f"[+{now - t0:5.2f}s Δ{gap:4.2f}s ERR] {b.decode().rstrip()}")
+
+        print("--- starting simulated apt-install ---")
+        r = await sh.run(APT_SIM, on_stdout=on_out, on_stderr=on_err)
+        total = time.monotonic() - t0
+        print("--- done ---")
+        print(f"exit={r.exit_code}  total_wall={total:.2f}s  "
+              f"stdout_chunks={out_count} stderr_chunks={err_count}")
+        print(f"stdout_bytes={len(r.stdout)} stderr_bytes={len(r.stderr)}")
+        await sh.close()
+    finally:
+        await sb.kill()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

opencomputer_sdk-0.5.4/examples/test_disk_size.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+Disk Size Test
+
+Verifies the `disk_mb` sandbox creation parameter:
+  1. Default (no arg) → 20GB workspace
+  2. Explicit 20GB    → 20GB workspace
+  3. Explicit 30GB    → 30GB workspace (requires org `max_disk_mb` >= 30720)
+  4. Below minimum    → rejected with 400
+
+Larger disk sizes are in closed beta — contact us to raise your org's
+max_disk_mb ceiling: https://cal.com/team/digger/opencomputer-founder-chat
+
+Usage:
+  python examples/test_disk_size.py
+
+Environment:
+  OPENCOMPUTER_API_URL  (default: http://localhost:8080)
+  OPENCOMPUTER_API_KEY  (default: test-key)
+"""
+
+import asyncio
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from opencomputer import Sandbox
+
+API_URL = os.environ.get("OPENCOMPUTER_API_URL", "http://localhost:8080")
+API_KEY = os.environ.get("OPENCOMPUTER_API_KEY", "test-key")
+
+GREEN = "\033[32m"
+RED = "\033[31m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+RESET = "\033[0m"
+
+passed = 0
+failed = 0
+
+
+def green(msg: str) -> None:
+    print(f"{GREEN}✓ {msg}{RESET}")
+
+
+def red(msg: str) -> None:
+    print(f"{RED}✗ {msg}{RESET}")
+
+
+def bold(msg: str) -> None:
+    print(f"{BOLD}{msg}{RESET}")
+
+
+def dim(msg: str) -> None:
+    print(f"{DIM}  {msg}{RESET}")
+
+
+async def run_case(label: str, disk_mb: int | None, expect_size: str | None, expect_reject: bool = False) -> None:
+    global passed, failed
+    bold(f"\n{label}")
+    kwargs = dict(api_url=API_URL, api_key=API_KEY, timeout=120)
+    if disk_mb is not None:
+        kwargs["disk_mb"] = disk_mb
+    try:
+        async with await Sandbox.create(**kwargs) as sb:
+            dim(f"created {sb.sandbox_id}")
+            r = await sb.exec.run("df -h /home/sandbox | tail -1")
+            dim(f"df: {r.stdout.strip()}")
+            if expect_reject:
+                red("expected rejection but sandbox was created")
+                failed += 1
+            elif expect_size and expect_size in r.stdout:
+                green(f"workspace reports {expect_size}")
+                passed += 1
+            else:
+                red(f"expected {expect_size} in df output")
+                failed += 1
+    except Exception as e:
+        if expect_reject:
+            green(f"rejected as expected ({str(e).splitlines()[0]})")
+            passed += 1
+        else:
+            red(f"unexpected error: {e}")
+            failed += 1
+
+
+async def main() -> None:
+    bold("OpenComputer SDK — disk size test")
+    dim(f"API: {API_URL}")
+
+    await run_case("default (no disk_mb)", None, "20G")
+    await run_case("explicit 20GB", 20480, "20G")
+    await run_case("30GB", 30720, "30G")
+    await run_case("below minimum (8GB)", 8192, None, expect_reject=True)
+
+    print()
+    bold(f"Results: {passed} passed, {failed} failed")
+    sys.exit(1 if failed > 0 else 0)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{opencomputer_sdk-0.5.2 → opencomputer_sdk-0.5.4}/examples/test_exec.py

@@ -86,7 +86,8 @@ async def main():
 
         # 8. exec.start() + list + kill
         print("\n--- 8. exec.start('sleep 60') + list + kill ---")
-        session_id = await sandbox.exec.start("sleep", args=["60"])
+        session = await sandbox.exec.start("sleep", args=["60"])
+        session_id = session.session_id
         print(f"  session: {session_id}")
 
         sessions = await sandbox.exec.list()

opencomputer_sdk-0.5.4/examples/test_shell.py

@@ -0,0 +1,222 @@
+"""test_shell.py — End-to-end test for exec.shell() (stateful shell sessions).
+
+Usage:
+    cd sdks/python
+    python examples/test_shell.py
+
+Environment:
+    OPENCOMPUTER_API_URL  (default: http://localhost:8080)
+    OPENCOMPUTER_API_KEY  (default: opensandbox-dev)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from opencomputer import Sandbox, ShellBusyError, ShellClosedError
+
+
+API_URL = os.environ.get("OPENCOMPUTER_API_URL", "http://localhost:8080")
+API_KEY = os.environ.get("OPENCOMPUTER_API_KEY", "opensandbox-dev")
+
+passed = 0
+failed = 0
+
+
+def check(cond: bool, msg: str) -> None:
+    global passed, failed
+    if cond:
+        passed += 1
+        print(f"  ✓ {msg}")
+    else:
+        failed += 1
+        print(f"  ✗ {msg}")
+
+
+async def main() -> None:
+    print("=== OpenSandbox Python Shell API Test ===\n")
+    print(f"API: {API_URL}")
+
+    print("\n--- 1. Creating sandbox ---")
+    sandbox = await Sandbox.create(api_url=API_URL, api_key=API_KEY, template="base")
+    print(f"  Sandbox: {sandbox.sandbox_id} ({sandbox.status})")
+    check(sandbox.status == "running", "sandbox is running")
+
+    try:
+        # 2. basic run + exit code
+        print("\n--- 2. shell.run('echo hello') ---")
+        sh = await sandbox.exec.shell()
+        r1 = await sh.run("echo hello")
+        print(f'  stdout: "{r1.stdout.strip()}" exit={r1.exit_code}')
+        check(r1.exit_code == 0, "exit 0")
+        check(r1.stdout.strip() == "hello", "stdout matches")
+        check(r1.stderr == "", "stderr empty")
+
+        # 3. cwd persists
+        print("\n--- 3. cwd persists across run() calls ---")
+        await sh.run("cd /tmp")
+        pwd = await sh.run("pwd")
+        print(f'  pwd: "{pwd.stdout.strip()}"')
+        check(pwd.stdout.strip() == "/tmp", "cwd persisted")
+
+        # 4. exported env persists
+        print("\n--- 4. exported env persists ---")
+        await sh.run("export MY_SHELL_VAR=persistence-works")
+        env_r = await sh.run("echo $MY_SHELL_VAR")
+        print(f'  echo: "{env_r.stdout.strip()}"')
+        check(env_r.stdout.strip() == "persistence-works", "env persisted")
+
+        # 5. non-zero exit — subshell so it doesn't kill the outer shell
+        print("\n--- 5. non-zero exit code ---")
+        r_fail = await sh.run("( exit 7 )")
+        print(f"  exit: {r_fail.exit_code}")
+        check(r_fail.exit_code == 7, f"exit 7 (got {r_fail.exit_code})")
+        r_fail2 = await sh.run("false && echo nope")
+        check(r_fail2.exit_code == 1, f"exit 1 from false (got {r_fail2.exit_code})")
+
+        # 6. stderr vs stdout separation
+        print("\n--- 6. stderr separated from stdout ---")
+        r_err = await sh.run("echo to-out; echo to-err >&2")
+        print(f'  stdout="{r_err.stdout.strip()}" stderr="{r_err.stderr.strip()}"')
+        check(r_err.stdout.strip() == "to-out", "stdout is to-out")
+        check(r_err.stderr.strip() == "to-err", "stderr is to-err")
+        check("__OC_" not in r_err.stderr, "sentinel token hidden from returned stderr")
+
+        # 7. streaming callbacks — print live so interleaving is visible,
+        # then assert chunks were spaced out in time (not buffered to the end).
+        print("\n--- 7. streaming callbacks ---")
+        import time
+        out_chunks: list[bytes] = []
+        err_chunks: list[bytes] = []
+        out_times: list[float] = []
+        err_times: list[float] = []
+        t0 = time.monotonic()
+
+        def on_out(b: bytes) -> None:
+            out_chunks.append(b)
+            out_times.append(time.monotonic())
+            print(f"    [+{time.monotonic() - t0:5.2f}s OUT] {b!r}")
+
+        def on_err(b: bytes) -> None:
+            err_chunks.append(b)
+            err_times.append(time.monotonic())
+            print(f"    [+{time.monotonic() - t0:5.2f}s ERR] {b!r}")
+
+        # Use /bin/echo (external) rather than bash's builtin — the builtin
+        # goes through glibc stdio which block-buffers when stdout is a pipe,
+        # so output lands in one chunk at the end. Each /bin/echo is a fresh
+        # process that flushes on exit, making the streaming observable.
+        r_stream = await sh.run(
+            "for i in 1 2 3; do /bin/echo stdout-$i; /bin/echo stderr-$i >&2; sleep 0.2; done",
+            on_stdout=on_out,
+            on_stderr=on_err,
+        )
+        joined_out = b"".join(out_chunks).decode()
+        joined_err = b"".join(err_chunks).decode()
+        check("stdout-1" in joined_out and "stdout-3" in joined_out, "stdout stream callbacks fired")
+        check("stderr-1" in joined_err and "stderr-3" in joined_err, "stderr stream callbacks fired")
+        check("__OC_" not in joined_err, "sentinel token hidden from on_stderr")
+        check(r_stream.exit_code == 0, "streaming run exits 0")
+        # Command sleeps 0.2s × 3 = 0.6s. Ideally chunks stream as they are
+        # produced. In practice, frames may be coalesced by upstream proxies
+        # (CF/ALB) or gRPC flow control, so a single-chunk delivery is legal
+        # — we log the span for visibility but don't fail on it.
+        stdout_span = (out_times[-1] - out_times[0]) if len(out_times) >= 2 else 0.0
+        print(f"    (stdout span across {len(out_times)} chunks: {stdout_span:.2f}s)")
+
+        # 8. concurrent run rejects
+        print("\n--- 8. concurrent run rejects ---")
+        slow_task = asyncio.create_task(sh.run("sleep 0.3; echo done"))
+        await asyncio.sleep(0.05)
+        busy_err: Exception | None = None
+        try:
+            await sh.run("echo should-not-run")
+        except Exception as e:
+            busy_err = e
+        check(isinstance(busy_err, ShellBusyError), "got ShellBusyError on concurrent run")
+        slow_r = await slow_task
+        check(slow_r.stdout.strip() == "done", "original run still completes")
+
+        # 9. shell functions persist
+        print("\n--- 9. shell functions persist ---")
+        await sh.run("greet() { echo hi-$1; }")
+        fn_r = await sh.run("greet world")
+        check(fn_r.stdout.strip() == "hi-world", "defined function callable in later run")
+
+        # 10. close
+        print("\n--- 10. close ---")
+        await sh.close()
+        closed_err: Exception | None = None
+        try:
+            await sh.run("echo after-close")
+        except Exception as e:
+            closed_err = e
+        check(isinstance(closed_err, ShellClosedError), "run after close rejects with ShellClosedError")
+
+        # 11. shell with cwd/env at construction
+        print("\n--- 11. shell(cwd=..., env=...) initial state ---")
+        sh2 = await sandbox.exec.shell(cwd="/etc", env={"SHELL_INIT_VAR": "from-init"})
+        r11a = await sh2.run("pwd")
+        check(r11a.stdout.strip() == "/etc", "initial cwd honored")
+        r11b = await sh2.run("echo $SHELL_INIT_VAR")
+        check(r11b.stdout.strip() == "from-init", "initial env honored")
+        await sh2.close()
+
+        # 12. terminal-tab semantic: `exit` in user command closes the shell
+        print("\n--- 12. exit N closes the shell (terminal-tab semantic) ---")
+        sh_exit = await sandbox.exec.shell()
+        exit_err: Exception | None = None
+        try:
+            await sh_exit.run("exit 42")
+        except Exception as e:
+            exit_err = e
+        check(isinstance(exit_err, ShellClosedError), "exit 42 rejects the pending run with ShellClosedError")
+        after_exit_err: Exception | None = None
+        try:
+            await sh_exit.run("echo after")
+        except Exception as e:
+            after_exit_err = e
+        check(isinstance(after_exit_err, ShellClosedError), "subsequent run rejects once shell is closed")
+
+        # 13. reattach to an open shell by sessionId
+        print("\n--- 13. reattach_shell revisits an open shell ---")
+        sh_a = await sandbox.exec.shell()
+        await sh_a.run("cd /tmp")
+        await sh_a.run("export REATTACH_VAR=round-trip")
+        reattach_id = sh_a.session_id
+        # Drop the reference without closing — server-side bash keeps running.
+        sh_b = await sandbox.exec.reattach_shell(reattach_id)
+        check(sh_b.session_id == reattach_id, "reattached shell has the same sessionId")
+        r_pwd = await sh_b.run("pwd")
+        check(r_pwd.stdout.strip() == "/tmp", f'reattach preserves cwd (got "{r_pwd.stdout.strip()}")')
+        r_env2 = await sh_b.run("echo $REATTACH_VAR")
+        check(r_env2.stdout.strip() == "round-trip", f'reattach preserves env (got "{r_env2.stdout.strip()}")')
+        await sh_b.close()
+
+        # 14. exec.background alias
+        print("\n--- 14. exec.background alias ---")
+        bg_exit = {"code": -999}
+
+        def on_bg_exit(code: int) -> None:
+            bg_exit["code"] = code
+
+        bg_sess = await sandbox.exec.background(
+            "sh", args=["-c", "echo bg-ok; sleep 0.2"], on_exit=on_bg_exit
+        )
+        await bg_sess.done
+        await bg_sess.close()
+        check(bg_exit["code"] == 0, f"exec.background returns exit code (got {bg_exit['code']})")
+
+    finally:
+        print("\n--- Killing sandbox ---")
+        await sandbox.kill()
+        check(sandbox.status == "stopped", "sandbox stopped")
+
+    print(f"\n=== Results: {passed} passed, {failed} failed ===")
+    if failed > 0:
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

opencomputer_sdk-0.5.4/opencomputer/__init__.py

@@ -0,0 +1,60 @@
+"""OpenComputer Python SDK - cloud sandbox platform."""
+
+from opencomputer.sandbox import Sandbox, ScalingLockedError, PlanLimitError
+from opencomputer.agent import Agent, AgentEvent, AgentSession, AgentSessionInfo
+from opencomputer.filesystem import Filesystem
+from opencomputer.exec import Exec, ProcessResult, ExecSession, ExecSessionInfo
+from opencomputer.image import Image
+from opencomputer.pty import Pty, PtySession
+from opencomputer.shell import Shell, ShellBusyError, ShellClosedError
+from opencomputer.template import Template
+from opencomputer.project import SecretStore
+from opencomputer.snapshot import Snapshots
+from opencomputer.usage import (
+    Usage,
+    Tags,
+    UsageSandboxItem,
+    UsageTagItem,
+    UsageTotals,
+    UsageUntaggedBucket,
+    UsageBySandboxResponse,
+    UsageByTagResponse,
+    SandboxUsageResponse,
+    TagKeyInfo,
+)
+
+__all__ = [
+    "Sandbox",
+    "ScalingLockedError",
+    "PlanLimitError",
+    "Agent",
+    "AgentEvent",
+    "AgentSession",
+    "AgentSessionInfo",
+    "Filesystem",
+    "Exec",
+    "ProcessResult",
+    "ExecSession",
+    "ExecSessionInfo",
+    "Image",
+    "Pty",
+    "PtySession",
+    "Shell",
+    "ShellBusyError",
+    "ShellClosedError",
+    "Template",
+    "SecretStore",
+    "Snapshots",
+    "Usage",
+    "Tags",
+    "UsageSandboxItem",
+    "UsageTagItem",
+    "UsageTotals",
+    "UsageUntaggedBucket",
+    "UsageBySandboxResponse",
+    "UsageByTagResponse",
+    "SandboxUsageResponse",
+    "TagKeyInfo",
+]
+
+__version__ = "0.5.4"