beadrun 0.1.0__py3-none-any.whl

beadrun/__init__.py

@@ -0,0 +1,16 @@
+"""bead sandboxes: one key, natural objects, automatic resource cleanup."""
+from .account import Bead as Bead, limits as limits, pricing as pricing
+from .async_account import AsyncBead as AsyncBead
+from .sandbox import Sandbox as Sandbox
+from .async_sandbox import AsyncSandbox as AsyncSandbox
+from .batches import Fleet as Fleet, Swarm as Swarm
+from .async_batches import AsyncFleet as AsyncFleet, AsyncSwarm as AsyncSwarm
+from .resources import Golden as Golden
+from .async_resources import AsyncGolden as AsyncGolden
+from .models import CommandResult as CommandResult, CommandEvent as CommandEvent, FileEntry as FileEntry
+from .errors import (
+    BeadError as BeadError, AuthenticationError as AuthenticationError, NotFoundError as NotFoundError,
+    TimeoutError as TimeoutError, ProtocolError as ProtocolError, LimitError as LimitError,
+    RateLimitError as RateLimitError, PaymentRequiredError as PaymentRequiredError, BatchError as BatchError,
+    AdmissionLimit as AdmissionLimit,
+)

beadrun/account.py

@@ -0,0 +1,46 @@
+"""Account-level usage, pricing and credential profiles."""
+from __future__ import annotations
+from typing import Any, Unpack
+from .models import ClientOptions
+from .resources import Profiles
+from .transport import Transport
+
+
+class Pricing:
+    def __init__(self, transport: Transport | None = None):
+        self.transport = transport
+
+    def estimate(self, *, vcpus: int, memory_mib: int, disk_mib: int, duration_seconds: int,
+                 paused: bool = False, machines: int = 1, **client: Unpack[ClientOptions]) -> dict[str, Any]:
+        transport = self.transport or Transport(client)
+        try:
+            return dict(transport.json("POST", "/v1/pricing/estimate", {
+                "vcpus": vcpus, "memory_mib": memory_mib, "disk_mib": disk_mib,
+                "duration_seconds": duration_seconds, "paused": paused, "machines": machines,
+            }))
+        finally:
+            if self.transport is None:
+                transport.close()
+
+
+class Bead:
+    def __init__(self, **client: Unpack[ClientOptions]):
+        self.transport = Transport(client)
+        self.profiles, self.pricing = Profiles(self.transport), Pricing(self.transport)
+
+    def limits(self) -> dict[str, Any]:
+        return dict(self.transport.json("GET", "/v1/limits"))
+
+    def close(self) -> None:
+        self.transport.close()
+
+
+pricing = Pricing()
+
+
+def limits(**client: Unpack[ClientOptions]) -> dict[str, Any]:
+    account = Bead(**client)
+    try:
+        return account.limits()
+    finally:
+        account.close()

beadrun/async_account.py

@@ -0,0 +1,40 @@
+# Generated by sdk/tools/generate_async.py; edit the sync owner.
+from __future__ import annotations
+'Account-level usage, pricing and credential profiles.'
+from typing import Any, Unpack
+from .models import ClientOptions
+from .async_resources import AsyncProfiles
+from .async_transport import AsyncTransport
+
+class AsyncPricing:
+
+    def __init__(self, transport: AsyncTransport | None=None):
+        self.transport = transport
+
+    async def estimate(self, *, vcpus: int, memory_mib: int, disk_mib: int, duration_seconds: int, paused: bool=False, machines: int=1, **client: Unpack[ClientOptions]) -> dict[str, Any]:
+        transport = self.transport or AsyncTransport(client)
+        try:
+            return dict(await transport.json('POST', '/v1/pricing/estimate', {'vcpus': vcpus, 'memory_mib': memory_mib, 'disk_mib': disk_mib, 'duration_seconds': duration_seconds, 'paused': paused, 'machines': machines}))
+        finally:
+            if self.transport is None:
+                await transport.close()
+
+class AsyncBead:
+
+    def __init__(self, **client: Unpack[ClientOptions]):
+        self.transport = AsyncTransport(client)
+        self.profiles, self.pricing = (AsyncProfiles(self.transport), AsyncPricing(self.transport))
+
+    async def limits(self) -> dict[str, Any]:
+        return dict(await self.transport.json('GET', '/v1/limits'))
+
+    async def close(self) -> None:
+        await self.transport.close()
+pricing = AsyncPricing()
+
+async def limits(**client: Unpack[ClientOptions]) -> dict[str, Any]:
+    account = AsyncBead(**client)
+    try:
+        return await account.limits()
+    finally:
+        await account.close()

beadrun/async_batches.py

@@ -0,0 +1,80 @@
+# Generated by sdk/tools/generate_async.py; edit the sync owner.
+from __future__ import annotations
+import asyncio
+from collections.abc import Iterator
+'Server-side fleets and durable swarm result iteration.'
+from collections.abc import AsyncIterator
+from types import TracebackType
+from typing import Any, Unpack
+from urllib.parse import quote
+import json
+import time
+from .errors import TimeoutError
+from .models import ClientOptions
+from .async_resources import async_wait_for
+from .async_sandbox import AsyncSandbox, async_create_request
+from .async_transport import AsyncTransport
+
+class AsyncFleet:
+
+    def __init__(self, sandboxes: list[AsyncSandbox], transport: AsyncTransport):
+        self.sandboxes, self.transport = (sandboxes, transport)
+
+    @classmethod
+    async def create(cls, n: int, *, template: str='base', timeout: int=300, env: dict[str, str] | None=None, **client: Unpack[ClientOptions]) -> AsyncFleet:
+        transport = AsyncTransport(client)
+        batch = await transport.json('POST', '/v2/sandboxes/fleet', {'count': n, 'request': await async_create_request(transport, template, timeout, env, None, None, None)}, True)
+        if batch.get('fleetID'):
+            id = str(batch['fleetID'])
+            batch = await async_wait_for(transport, lambda: transport.json('GET', '/v2/sandboxes/fleets/' + quote(id, safe='')), lambda b: bool(b.get('results')) and all((r['status'] != 202 for r in b['results'])))
+        return cls(AsyncSandbox.members(batch.get('results', []), transport), transport)
+
+    def __iter__(self) -> Iterator[AsyncSandbox]:
+        return iter(self.sandboxes)
+
+    async def kill(self) -> None:
+        failures: list[Exception] = []
+        for sandbox in self.sandboxes:
+            try:
+                await sandbox.kill()
+            except Exception as exc:
+                failures.append(exc)
+        if failures:
+            raise failures[0]
+
+    async def __aenter__(self) -> AsyncFleet:
+        return self
+
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None) -> None:
+        await self.kill()
+
+class AsyncSwarm:
+
+    def __init__(self, id: str, transport: AsyncTransport):
+        self.id, self.transport = (id, transport)
+
+    @classmethod
+    async def run(cls, *, cmd: str, inputs: list[Any], template: str='base', timeout: int=300, concurrency: int=8, task_retries: int=0, output_files: list[str] | None=None, **client: Unpack[ClientOptions]) -> AsyncSwarm:
+        transport = AsyncTransport(client)
+        result = await transport.json('POST', '/swarms', {'template': template, 'command': cmd, 'inputs': inputs, 'time_limit_seconds': timeout, 'concurrency': concurrency, 'retries': task_retries, 'output_files': output_files or []}, True)
+        return cls(str(result['id']), transport)
+
+    async def status(self) -> dict[str, Any]:
+        return dict(await self.transport.json('GET', '/swarms/' + quote(self.id, safe='')))
+
+    async def cancel(self) -> None:
+        await self.transport.json('POST', '/swarms/' + quote(self.id, safe='') + '/cancel')
+
+    async def __aiter__(self) -> AsyncIterator[dict[str, Any]]:
+        deadline = time.monotonic() + self.transport.options.get('operation_timeout', 600)
+        while (await self.status())['state'] in ('queued', 'running'):
+            if time.monotonic() >= deadline:
+                raise TimeoutError('Swarm wait expired. Inspect status or call swarm.cancel().')
+            await asyncio.sleep(self.transport.options.get('poll_interval', 1))
+        async with self.transport.stream('GET', '/swarms/' + quote(self.id, safe='') + '/results') as response:
+            async for line in response.aiter_lines():
+                if line.strip():
+                    yield json.loads(line)
+
+    async def close(self) -> None:
+        await self.transport.close()

beadrun/async_commands.py

@@ -0,0 +1,113 @@
+# Generated by sdk/tools/generate_async.py; edit the sync owner.
+from __future__ import annotations
+from collections.abc import Awaitable
+'Connect streaming without a protobuf runtime dependency.'
+from collections.abc import AsyncIterator
+from typing import Any, Literal, Protocol, overload
+import base64
+import codecs
+import json
+import struct
+import time
+from .http_types import AsyncResponseProtocol
+from .errors import ProtocolError, TimeoutError, api_error
+from .models import CommandEvent, CommandResult, OutputCallback
+from .async_transport import AsyncTransport
+
+class AsyncGuest(Protocol):
+    transport: AsyncTransport
+
+    def guest(self) -> tuple[str, dict[str, str]]:
+        ...
+
+async def async_frames(response: AsyncResponseProtocol) -> AsyncIterator[dict[str, Any]]:
+    buffer = b''
+    async for chunk in response.aiter_bytes():
+        buffer += chunk
+        while len(buffer) >= 5:
+            flags, length = struct.unpack('!BI', buffer[:5])
+            if length > 8 * 1024 * 1024:
+                raise ProtocolError('Command frame exceeds 8 MiB.')
+            if len(buffer) < 5 + length:
+                break
+            frame: dict[str, Any] = json.loads(buffer[5:5 + length])
+            buffer = buffer[5 + length:]
+            if flags == 2:
+                if frame.get('error'):
+                    raise api_error(500, frame['error'])
+                if buffer:
+                    raise ProtocolError('Unexpected bytes after stream trailer.')
+                return
+            if flags != 0:
+                raise ProtocolError('Unsupported Connect stream compression.')
+            yield frame
+    raise ProtocolError('Command stream ended without a Connect trailer; command may still be running.')
+
+class AsyncCommands:
+
+    def __init__(self, sandbox: AsyncGuest):
+        self.sandbox = sandbox
+
+    @overload
+    def run(self, cmd: str, *, stream: Literal[True], cwd: str | None=None, env: dict[str, str] | None=None, timeout: float=60, on_stdout: OutputCallback | None=None, on_stderr: OutputCallback | None=None) -> AsyncIterator[CommandEvent]:
+        ...
+
+    @overload
+    def run(self, cmd: str, *, stream: Literal[False]=False, cwd: str | None=None, env: dict[str, str] | None=None, timeout: float=60, on_stdout: OutputCallback | None=None, on_stderr: OutputCallback | None=None) -> Awaitable[CommandResult]:
+        ...
+
+    def run(self, cmd: str, *, stream: bool=False, cwd: str | None=None, env: dict[str, str] | None=None, timeout: float=60, on_stdout: OutputCallback | None=None, on_stderr: OutputCallback | None=None) -> AsyncIterator[CommandEvent] | Awaitable[CommandResult]:
+        if stream:
+            return self.stream(cmd, cwd=cwd, env=env, timeout=timeout, on_stdout=on_stdout, on_stderr=on_stderr)
+        return self.collect(cmd, cwd=cwd, env=env, timeout=timeout, on_stdout=on_stdout, on_stderr=on_stderr)
+
+    async def collect(self, cmd: str, *, cwd: str | None=None, env: dict[str, str] | None=None, timeout: float=60, on_stdout: OutputCallback | None=None, on_stderr: OutputCallback | None=None) -> CommandResult:
+        output = {'stdout': '', 'stderr': ''}
+        exit_code = 0
+        async for event in self.stream(cmd, cwd=cwd, env=env, timeout=timeout, on_stdout=on_stdout, on_stderr=on_stderr):
+            if event.type in output:
+                output[event.type] += event.data
+            elif event.type == 'exit':
+                exit_code = event.exit_code or 0
+        return CommandResult(exit_code, output['stdout'], output['stderr'])
+
+    async def stream(self, cmd: str, *, cwd: str | None=None, env: dict[str, str] | None=None, timeout: float=60, on_stdout: OutputCallback | None=None, on_stderr: OutputCallback | None=None) -> AsyncIterator[CommandEvent]:
+        url, headers = self.sandbox.guest()
+        process: dict[str, Any] = {'cmd': '/bin/bash', 'args': ['-lc', cmd], 'envs': env or {}}
+        if cwd is not None:
+            process['cwd'] = cwd
+        headers.update({'content-type': 'application/connect+json', 'connect-protocol-version': '1', 'connect-timeout-ms': str(int(timeout * 1000))})
+        payload = json.dumps({'process': process, 'stdin': False}).encode()
+        envelope = struct.pack('!BI', 0, len(payload)) + payload
+        ended = False
+        decoders = {kind: codecs.getincrementaldecoder('utf-8')('replace') for kind in ('stdout', 'stderr')}
+        deadline = time.monotonic() + timeout
+        async with self.sandbox.transport.stream('POST', url + '/process.Process/Start', content=envelope, headers=headers, timeout=timeout) as response:
+            async for frame in async_frames(response):
+                if time.monotonic() > deadline:
+                    raise TimeoutError('Command wait expired; kill the sandbox to stop all processes.')
+                event = frame.get('event', {})
+                if 'start' in event:
+                    yield CommandEvent('start', pid=event['start']['pid'])
+                for kind in ('stdout', 'stderr'):
+                    if kind in event.get('data', {}):
+                        data = decoders[kind].decode(base64.b64decode(event['data'][kind]))
+                        callback = on_stdout if kind == 'stdout' else on_stderr
+                        if callback:
+                            callback(data)
+                        yield CommandEvent('stdout' if kind == 'stdout' else 'stderr', data=data)
+                if 'end' in event:
+                    end = event['end']
+                    if end.get('error') and (not end.get('exited')):
+                        raise ProtocolError(str(end['error']))
+                    ended = True
+                    for kind in ('stdout', 'stderr'):
+                        data = decoders[kind].decode(b'', final=True)
+                        if data:
+                            callback = on_stdout if kind == 'stdout' else on_stderr
+                            if callback:
+                                callback(data)
+                            yield CommandEvent('stdout' if kind == 'stdout' else 'stderr', data=data)
+                    yield CommandEvent('exit', exit_code=int(end.get('exitCode', 0)))
+        if not ended:
+            raise ProtocolError('Command stream closed without exit. Inspect command state before retrying.')

beadrun/async_files.py

@@ -0,0 +1,42 @@
+# Generated by sdk/tools/generate_async.py; edit the sync owner.
+from __future__ import annotations
+import asyncio
+'Portable bytes and explicit local transfers.'
+from pathlib import Path
+from urllib.parse import quote
+from typing import Any
+import json
+import builtins
+from .async_commands import AsyncGuest
+from .models import FileEntry
+
+class AsyncFiles:
+
+    def __init__(self, sandbox: AsyncGuest):
+        self.sandbox = sandbox
+
+    async def read(self, path: str) -> str:
+        return (await self.read_bytes(path)).decode()
+
+    async def read_bytes(self, path: str) -> bytes:
+        url, headers = self.sandbox.guest()
+        return await self.sandbox.transport.request('GET', url + '/files?path=' + quote(path, safe=''), headers=headers)
+
+    async def write(self, path: str, content: str | bytes) -> None:
+        url, headers = self.sandbox.guest()
+        headers['content-type'] = 'application/octet-stream'
+        await self.sandbox.transport.request('POST', url + '/files?path=' + quote(path, safe=''), content.encode() if isinstance(content, str) else content, headers)
+
+    async def list(self, path: str='/') -> builtins.list[FileEntry]:
+        url, headers = self.sandbox.guest()
+        headers.update({'content-type': 'application/json', 'connect-protocol-version': '1'})
+        data: dict[str, Any] = json.loads(await self.sandbox.transport.request('POST', url + '/filesystem.Filesystem/ListDir', json.dumps({'path': path, 'depth': 1}).encode(), headers, True))
+        return [FileEntry(str(e['name']), str(e['path']), str(e.get('type', '')), int(e.get('size', 0)), str(e.get('permissions', ''))) for e in data.get('entries', [])]
+
+    async def upload(self, local_path: str | Path, remote_path: str) -> None:
+        await self.write(remote_path, await asyncio.to_thread(Path(local_path).read_bytes))
+
+    async def download(self, remote_path: str, local_path: str | Path) -> Path:
+        target = Path(local_path)
+        await asyncio.to_thread(target.write_bytes, await self.read_bytes(remote_path))
+        return target

beadrun/async_http.py

@@ -0,0 +1,91 @@
+"""Async HTTP using bounded urllib3 socket reads outside the event loop.
+
+The sync HTTP owner supplies TLS, framing and timeout behavior. Cancellation
+waits for the current bounded socket operation before releasing its connection.
+"""
+from __future__ import annotations
+from collections.abc import AsyncIterator, Callable, Mapping
+from contextlib import asynccontextmanager
+from typing import Any, TypeVar
+import asyncio
+import urllib3
+from .http import HttpClient, Response
+from .http_types import AsyncResponseProtocol, HTTPTimeoutError
+
+T = TypeVar('T')
+
+
+async def offload(operation: Callable[[], T]) -> T:
+    task = asyncio.create_task(asyncio.to_thread(operation))
+    try:
+        return await asyncio.shield(task)
+    except urllib3.exceptions.TimeoutError as exc:
+        raise HTTPTimeoutError() from exc
+    except asyncio.CancelledError:
+        try:
+            await task
+        finally:
+            raise
+
+
+class AsyncResponse:
+    def __init__(self, raw: Response):
+        self.raw = raw
+        self.status_code = raw.status_code
+        self.headers: Mapping[str, str] = raw.headers
+
+    @property
+    def is_success(self) -> bool:
+        return self.raw.is_success
+
+    async def aread(self) -> bytes:
+        return await offload(self.raw.read)
+
+    def json(self) -> Any:
+        return self.raw.json()
+
+    async def aiter_bytes(self) -> AsyncIterator[bytes]:
+        iterator = self.raw.iter_bytes()
+        while True:
+            item = await offload(lambda: next(iterator, None))
+            if item is None:
+                return
+            yield item
+
+    async def aiter_lines(self) -> AsyncIterator[str]:
+        iterator = self.raw.iter_lines()
+        while True:
+            item = await offload(lambda: next(iterator, None))
+            if item is None:
+                return
+            yield item
+
+
+class AsyncHttpClient:
+    def __init__(self, *, headers: dict[str, str]):
+        self.client = HttpClient(headers=headers)
+
+    @asynccontextmanager
+    async def stream(self, method: str, url: str, *, content: bytes | None,
+                     headers: dict[str, str], timeout: float) -> AsyncIterator[AsyncResponseProtocol]:
+        context = self.client.stream(method, url, content=content, headers=headers, timeout=timeout)
+        task = asyncio.create_task(asyncio.to_thread(context.__enter__))
+        entered = False
+        try:
+            try:
+                raw = await asyncio.shield(task)
+            except asyncio.CancelledError:
+                await task
+                entered = True
+                raise
+            entered = True
+            # HttpClient is the sole concrete owner of this response.
+            if not isinstance(raw, Response):
+                raise TypeError('Unexpected HTTP response implementation')
+            yield AsyncResponse(raw)
+        finally:
+            if entered:
+                await offload(lambda: context.__exit__(None, None, None))
+
+    async def aclose(self) -> None:
+        await offload(self.client.close)

beadrun/async_resources.py

@@ -0,0 +1,100 @@
+# Generated by sdk/tools/generate_async.py; edit the sync owner.
+from __future__ import annotations
+import asyncio
+from collections.abc import Awaitable
+'Publication waits, cursor-based agent events and credential metadata.'
+from collections.abc import Callable, AsyncIterator
+from typing import Any, TypeVar
+from urllib.parse import quote
+import time
+import builtins
+import uuid
+from .errors import BeadError, TimeoutError
+from .async_transport import AsyncTransport
+T = TypeVar('T')
+
+async def async_wait_for(transport: AsyncTransport, read: Callable[[], Awaitable[T]], ready: Callable[[T], bool]) -> T:
+    deadline = time.monotonic() + transport.options.get('operation_timeout', 600)
+    while True:
+        value = await read()
+        if ready(value):
+            return value
+        if time.monotonic() >= deadline:
+            raise TimeoutError('Operation wait expired. Inspect resource status before retrying.')
+        await asyncio.sleep(transport.options.get('poll_interval', 1))
+
+class AsyncGolden:
+
+    def __init__(self, info: dict[str, Any], transport: AsyncTransport):
+        self.info, self.transport = (info, transport)
+        self.deleted = False
+        transport.retain()
+        self.id = str(info['snapshotID'])
+
+    async def wait(self) -> AsyncGolden:
+
+        def ready(info: dict[str, Any]) -> bool:
+            if info['status'] in ('error', 'failed', 'retired', 'unavailable'):
+                raise BeadError('Golden publication failed. Inspect snapshot status and retry capture.')
+            return bool(info['status'] == 'ready')
+
+        async def read() -> dict[str, Any]:
+            return dict(await self.transport.json('GET', '/snapshots/' + quote(self.id, safe='')))
+        info: dict[str, Any] = await async_wait_for(self.transport, read, ready)
+        self.info.update(info)
+        return self
+
+    async def delete(self) -> None:
+        if not self.deleted:
+            await self.transport.json('DELETE', '/snapshots/' + quote(self.id, safe=''))
+            self.deleted = True
+            await self.transport.release()
+
+class AsyncAgent:
+
+    def __init__(self, transport: AsyncTransport, path: str):
+        self.transport, self.path = (transport, path)
+
+    async def prompt(self, prompt: str, *, cwd: str='/home/user', profile_id: str | None=None, model: str | None=None, timeout: float=600, approval_policy: str='untrusted') -> AsyncIterator[dict[str, Any]]:
+        accepted = await self.transport.json('POST', self.path + '/prompt', {'requestId': str(uuid.uuid4()), 'prompt': prompt, 'cwd': cwd, 'profileId': profile_id, 'model': model, 'approvalPolicy': approval_policy})
+        cursor = max(0, int(accepted.get('cursor', 1)) - 1)
+        deadline = time.monotonic() + timeout
+        while True:
+            page = await self.transport.json('GET', self.path + f'/events?after={cursor}')
+            for event in page['events']:
+                turn = accepted['turnId']
+                if event.get('turnId') != turn:
+                    continue
+                yield event
+                kind = event['event'].get('method', event['event'].get('type'))
+                if kind == 'bead/recoveryRequired':
+                    raise BeadError('Agent recovery required. Inspect conversation status and restart the runner before prompting again.')
+                if turn and event.get('turnId') == turn and (kind in ('turn/completed', 'turn/failed', 'bead/terminal')):
+                    return
+            cursor = int(page['cursor'])
+            if time.monotonic() >= deadline:
+                raise TimeoutError('Agent wait expired. Inspect conversation or interrupt the runner.')
+            await asyncio.sleep(self.transport.options.get('poll_interval', 1))
+
+    async def status(self) -> dict[str, Any]:
+        return dict(await self.transport.json('GET', self.path + '/conversation'))
+
+    async def interrupt(self, turn_id: str) -> Any:
+        return await self.transport.json('POST', self.path + '/runner/interrupt', {'requestId': str(uuid.uuid4()), 'expectedTurnId': turn_id})
+
+class AsyncProfiles:
+
+    def __init__(self, transport: AsyncTransport):
+        self.transport = transport
+
+    async def list(self) -> builtins.list[dict[str, Any]]:
+        return list(await self.transport.json('GET', '/credential-profiles'))
+
+    async def put(self, id: str, name: str, material: dict[str, Any]) -> Any:
+        return await self.transport.json('PUT', '/credential-profiles/' + quote(id, safe=''), {'name': name, 'material': material})
+
+    async def revoke(self, id: str) -> None:
+        await self.transport.json('POST', '/credential-profiles/' + quote(id, safe='') + '/revoke')
+
+    async def delete(self, id: str) -> None:
+        await self.transport.json('DELETE', '/credential-profiles/' + quote(id, safe=''))