boxd 0.3.2__tar.gz → 0.3.2.dev1182__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {boxd-0.3.2/src/boxd.egg-info → boxd-0.3.2.dev1182}/PKG-INFO +82 -1
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/README.md +81 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/pyproject.toml +1 -1
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/__init__.py +54 -0
- boxd-0.3.2.dev1182/src/boxd/_generated/api_pb2.py +816 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_generated/api_pb2_grpc.py +407 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_mappers.py +222 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_regions.py +5 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_requests.py +12 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/models.py +321 -1
- boxd-0.3.2.dev1182/src/boxd/resources/agents.py +615 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/machines.py +3 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182/src/boxd.egg-info}/PKG-INFO +82 -1
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd.egg-info/SOURCES.txt +2 -0
- boxd-0.3.2.dev1182/tests/test_agents.py +921 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_regions.py +38 -0
- boxd-0.3.2/src/boxd/_generated/api_pb2.py +0 -740
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/LICENSE +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/setup.cfg +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_client.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_credentials.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_generated/__init__.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_streaming.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_transport.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_urls.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_version_check.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/computer_use.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/errors.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/py.typed +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/__init__.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/account.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/computer.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/credentials.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/disks.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/domains.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/fs.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/orgs.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/regions.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/snapshots.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/teams.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/vars.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/spec.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd.egg-info/dependency_links.txt +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd.egg-info/requires.txt +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd.egg-info/top_level.txt +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_computer.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_computer_use.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_create_in_one_call.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_credentials.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_delete_self.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_fs.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_mappers.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_namespaces.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_python_versions.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_raw_key.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_requests.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_spec.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_streaming.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_transport.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_urls.py +0 -0
- {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_version_check.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: boxd
|
|
3
|
-
Version: 0.3.2
|
|
3
|
+
Version: 0.3.2.dev1182
|
|
4
4
|
Summary: Python SDK for the boxd cloud VM platform
|
|
5
5
|
Author: Azin
|
|
6
6
|
License-Expression: MIT
|
|
@@ -1038,6 +1038,87 @@ The model does whatever it decides to on the machine, as the machine's user:
|
|
|
1038
1038
|
give it a machine of its own. A complete Claude agent:
|
|
1039
1039
|
[`examples/claude_computer_use.py`](https://github.com/boxd-sh/sdk/blob/main/python/examples/claude_computer_use.py).
|
|
1040
1040
|
|
|
1041
|
+
### Coding agents
|
|
1042
|
+
|
|
1043
|
+
`machines.agents` runs Claude Code or Codex inside a machine through one API.
|
|
1044
|
+
A session is one conversation with one agent; each message you send runs as a
|
|
1045
|
+
turn, one at a time, and everything the turn does comes back as typed events,
|
|
1046
|
+
numbered by `seq`. The agent keeps working if you disconnect: pass the last
|
|
1047
|
+
`seq` you saw as `after_seq` to pick up where you left off.
|
|
1048
|
+
|
|
1049
|
+
```python
|
|
1050
|
+
agents = boxd.machines.agents
|
|
1051
|
+
|
|
1052
|
+
session = agents.start("my-box", "claude-code", cwd="/home/boxd/app")
|
|
1053
|
+
sent = agents.send("my-box", session.id, "Add a /health endpoint and a test for it")
|
|
1054
|
+
for event in agents.events("my-box", session.id, follow=True):
|
|
1055
|
+
if event.type == "message.delta":
|
|
1056
|
+
print(event.text, end="", flush=True)
|
|
1057
|
+
elif event.type == "tool.started":
|
|
1058
|
+
print(f"\n▸ {event.name} {event.input}")
|
|
1059
|
+
elif event.type == "turn.finished" and event.turn == sent.turn:
|
|
1060
|
+
print(f"\n[{event.reason}]")
|
|
1061
|
+
break
|
|
1062
|
+
agents.close("my-box", session.id)
|
|
1063
|
+
```
|
|
1064
|
+
|
|
1065
|
+
`send` returns once the message is delivered, not when the turn ends:
|
|
1066
|
+
`sent.turn` is the turn it started, joined or will start, and `sent.delivery`
|
|
1067
|
+
says how (`"started"`, `"queued"`, `"joined"`, `"queued_fallback"`). A message
|
|
1068
|
+
sent while a turn runs waits as a turn of its own; `send(..., when="now")` adds
|
|
1069
|
+
it to the running turn instead. `timeout_secs=` and `max_steps=` interrupt a
|
|
1070
|
+
turn the message starts after that many seconds or steps (model calls for
|
|
1071
|
+
Claude Code, tool calls for Codex). `interrupt()` stops the running turn
|
|
1072
|
+
(`clear_queue=True` also drops the waiting messages), `close()` ends the
|
|
1073
|
+
session, and `list(machine, all=True)` also shows closed and failed sessions.
|
|
1074
|
+
`harnesses()` lists the agents a machine can run.
|
|
1075
|
+
|
|
1076
|
+
`start` and `send` are retried after a lost connection without running
|
|
1077
|
+
anything twice: each carries a `request_id`, and a repeat with the same one
|
|
1078
|
+
gets the first answer. The SDK makes up a new one for each call; pass
|
|
1079
|
+
`request_id=` yourself to retry from another process, such as an automation
|
|
1080
|
+
running a step again.
|
|
1081
|
+
|
|
1082
|
+
The events are `AgentTurnStarted`, `AgentUserMessage`, `AgentMessageDelta`,
|
|
1083
|
+
`AgentMessage`, `AgentThinkingDelta`, `AgentToolStarted`, `AgentToolOutput`,
|
|
1084
|
+
`AgentToolFinished`, `AgentPlan`, `AgentUsage` and `AgentTurnFinished`, told
|
|
1085
|
+
apart by `type`; every turn ends with `turn.finished` and its `reason`
|
|
1086
|
+
(`"done"`, `"interrupted"`, `"timeout"`, `"max_steps"`, `"max_tokens"`,
|
|
1087
|
+
`"refused"`, `"failed"`). An event of a type this SDK doesn't know is skipped.
|
|
1088
|
+
Without `follow`, `events()` ends after the latest event; with it, it has no
|
|
1089
|
+
deadline and stops when you stop iterating.
|
|
1090
|
+
|
|
1091
|
+
`runs()` reads how finished turns went from the platform's run history, newest
|
|
1092
|
+
first, across the machines you can see:
|
|
1093
|
+
|
|
1094
|
+
```python
|
|
1095
|
+
from datetime import datetime, timedelta, timezone
|
|
1096
|
+
|
|
1097
|
+
page = agents.runs(machine="my-box", since=datetime.now(timezone.utc) - timedelta(days=1))
|
|
1098
|
+
for run in page.runs:
|
|
1099
|
+
print(run.session_id, run.turn, run.reason, run.error or "")
|
|
1100
|
+
# page.next_page_token, passed as page_token=, reads the next, older page;
|
|
1101
|
+
# iter_runs() reads every page for you.
|
|
1102
|
+
```
|
|
1103
|
+
|
|
1104
|
+
Each `AgentRun` has the machine, the session, the turn, the agent and its
|
|
1105
|
+
version, how the turn started and ended (`reason`, `error`), when, its steps and
|
|
1106
|
+
its tokens, but no prompts or output. Filter by `machine`, `session` and
|
|
1107
|
+
`since`; `limit` is 50 by default, at most 500. Reading the history never wakes
|
|
1108
|
+
a machine, and it keeps 30 days of runs, also after a machine is deleted. A
|
|
1109
|
+
cluster that doesn't keep run history (some self-hosted ones) answers with a
|
|
1110
|
+
`ConflictError`.
|
|
1111
|
+
|
|
1112
|
+
The agent runs as the machine's user without asking before it acts, with the
|
|
1113
|
+
machine's env vars and secrets (`env=` adds more). Give it a key as a secret
|
|
1114
|
+
(`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`, bound to its provider's host so the
|
|
1115
|
+
machine only holds a placeholder), or sign Claude Code or Codex in once and
|
|
1116
|
+
boxd serves the login to your private machines. The machine stays awake while
|
|
1117
|
+
a turn runs. `start`, `send` and `interrupt` are sent once: a lost answer is
|
|
1118
|
+
not retried, since that could start a second session or deliver a message
|
|
1119
|
+
twice. `AsyncBoxd` has the same methods, awaited, and `events()` there is an
|
|
1120
|
+
async iterator. More: [Coding agent sessions](https://docs.boxd.sh/guides/coding-agents).
|
|
1121
|
+
|
|
1041
1122
|
### Ports and proxies
|
|
1042
1123
|
|
|
1043
1124
|
```python
|
|
@@ -1003,6 +1003,87 @@ The model does whatever it decides to on the machine, as the machine's user:
|
|
|
1003
1003
|
give it a machine of its own. A complete Claude agent:
|
|
1004
1004
|
[`examples/claude_computer_use.py`](https://github.com/boxd-sh/sdk/blob/main/python/examples/claude_computer_use.py).
|
|
1005
1005
|
|
|
1006
|
+
### Coding agents
|
|
1007
|
+
|
|
1008
|
+
`machines.agents` runs Claude Code or Codex inside a machine through one API.
|
|
1009
|
+
A session is one conversation with one agent; each message you send runs as a
|
|
1010
|
+
turn, one at a time, and everything the turn does comes back as typed events,
|
|
1011
|
+
numbered by `seq`. The agent keeps working if you disconnect: pass the last
|
|
1012
|
+
`seq` you saw as `after_seq` to pick up where you left off.
|
|
1013
|
+
|
|
1014
|
+
```python
|
|
1015
|
+
agents = boxd.machines.agents
|
|
1016
|
+
|
|
1017
|
+
session = agents.start("my-box", "claude-code", cwd="/home/boxd/app")
|
|
1018
|
+
sent = agents.send("my-box", session.id, "Add a /health endpoint and a test for it")
|
|
1019
|
+
for event in agents.events("my-box", session.id, follow=True):
|
|
1020
|
+
if event.type == "message.delta":
|
|
1021
|
+
print(event.text, end="", flush=True)
|
|
1022
|
+
elif event.type == "tool.started":
|
|
1023
|
+
print(f"\n▸ {event.name} {event.input}")
|
|
1024
|
+
elif event.type == "turn.finished" and event.turn == sent.turn:
|
|
1025
|
+
print(f"\n[{event.reason}]")
|
|
1026
|
+
break
|
|
1027
|
+
agents.close("my-box", session.id)
|
|
1028
|
+
```
|
|
1029
|
+
|
|
1030
|
+
`send` returns once the message is delivered, not when the turn ends:
|
|
1031
|
+
`sent.turn` is the turn it started, joined or will start, and `sent.delivery`
|
|
1032
|
+
says how (`"started"`, `"queued"`, `"joined"`, `"queued_fallback"`). A message
|
|
1033
|
+
sent while a turn runs waits as a turn of its own; `send(..., when="now")` adds
|
|
1034
|
+
it to the running turn instead. `timeout_secs=` and `max_steps=` interrupt a
|
|
1035
|
+
turn the message starts after that many seconds or steps (model calls for
|
|
1036
|
+
Claude Code, tool calls for Codex). `interrupt()` stops the running turn
|
|
1037
|
+
(`clear_queue=True` also drops the waiting messages), `close()` ends the
|
|
1038
|
+
session, and `list(machine, all=True)` also shows closed and failed sessions.
|
|
1039
|
+
`harnesses()` lists the agents a machine can run.
|
|
1040
|
+
|
|
1041
|
+
`start` and `send` are retried after a lost connection without running
|
|
1042
|
+
anything twice: each carries a `request_id`, and a repeat with the same one
|
|
1043
|
+
gets the first answer. The SDK makes up a new one for each call; pass
|
|
1044
|
+
`request_id=` yourself to retry from another process, such as an automation
|
|
1045
|
+
running a step again.
|
|
1046
|
+
|
|
1047
|
+
The events are `AgentTurnStarted`, `AgentUserMessage`, `AgentMessageDelta`,
|
|
1048
|
+
`AgentMessage`, `AgentThinkingDelta`, `AgentToolStarted`, `AgentToolOutput`,
|
|
1049
|
+
`AgentToolFinished`, `AgentPlan`, `AgentUsage` and `AgentTurnFinished`, told
|
|
1050
|
+
apart by `type`; every turn ends with `turn.finished` and its `reason`
|
|
1051
|
+
(`"done"`, `"interrupted"`, `"timeout"`, `"max_steps"`, `"max_tokens"`,
|
|
1052
|
+
`"refused"`, `"failed"`). An event of a type this SDK doesn't know is skipped.
|
|
1053
|
+
Without `follow`, `events()` ends after the latest event; with it, it has no
|
|
1054
|
+
deadline and stops when you stop iterating.
|
|
1055
|
+
|
|
1056
|
+
`runs()` reads how finished turns went from the platform's run history, newest
|
|
1057
|
+
first, across the machines you can see:
|
|
1058
|
+
|
|
1059
|
+
```python
|
|
1060
|
+
from datetime import datetime, timedelta, timezone
|
|
1061
|
+
|
|
1062
|
+
page = agents.runs(machine="my-box", since=datetime.now(timezone.utc) - timedelta(days=1))
|
|
1063
|
+
for run in page.runs:
|
|
1064
|
+
print(run.session_id, run.turn, run.reason, run.error or "")
|
|
1065
|
+
# page.next_page_token, passed as page_token=, reads the next, older page;
|
|
1066
|
+
# iter_runs() reads every page for you.
|
|
1067
|
+
```
|
|
1068
|
+
|
|
1069
|
+
Each `AgentRun` has the machine, the session, the turn, the agent and its
|
|
1070
|
+
version, how the turn started and ended (`reason`, `error`), when, its steps and
|
|
1071
|
+
its tokens, but no prompts or output. Filter by `machine`, `session` and
|
|
1072
|
+
`since`; `limit` is 50 by default, at most 500. Reading the history never wakes
|
|
1073
|
+
a machine, and it keeps 30 days of runs, also after a machine is deleted. A
|
|
1074
|
+
cluster that doesn't keep run history (some self-hosted ones) answers with a
|
|
1075
|
+
`ConflictError`.
|
|
1076
|
+
|
|
1077
|
+
The agent runs as the machine's user without asking before it acts, with the
|
|
1078
|
+
machine's env vars and secrets (`env=` adds more). Give it a key as a secret
|
|
1079
|
+
(`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`, bound to its provider's host so the
|
|
1080
|
+
machine only holds a placeholder), or sign Claude Code or Codex in once and
|
|
1081
|
+
boxd serves the login to your private machines. The machine stays awake while
|
|
1082
|
+
a turn runs. `start`, `send` and `interrupt` are sent once: a lost answer is
|
|
1083
|
+
not retried, since that could start a second session or deliver a message
|
|
1084
|
+
twice. `AsyncBoxd` has the same methods, awaited, and `events()` there is an
|
|
1085
|
+
async iterator. More: [Coding agent sessions](https://docs.boxd.sh/guides/coding-agents).
|
|
1086
|
+
|
|
1006
1087
|
### Ports and proxies
|
|
1007
1088
|
|
|
1008
1089
|
```python
|
|
@@ -40,6 +40,32 @@ from .errors import (
|
|
|
40
40
|
)
|
|
41
41
|
from .models import (
|
|
42
42
|
Account,
|
|
43
|
+
AgentDelivery,
|
|
44
|
+
AgentEvent,
|
|
45
|
+
AgentEventBase,
|
|
46
|
+
AgentFinishReason,
|
|
47
|
+
AgentInterruptResult,
|
|
48
|
+
AgentMessage,
|
|
49
|
+
AgentMessageDelta,
|
|
50
|
+
AgentPlan,
|
|
51
|
+
AgentPlanItem,
|
|
52
|
+
AgentRun,
|
|
53
|
+
AgentRunStartedBy,
|
|
54
|
+
AgentRunUsage,
|
|
55
|
+
AgentRunsPage,
|
|
56
|
+
AgentSendResult,
|
|
57
|
+
AgentSendWhen,
|
|
58
|
+
AgentSession,
|
|
59
|
+
AgentSessionState,
|
|
60
|
+
AgentThinkingDelta,
|
|
61
|
+
AgentToolFinished,
|
|
62
|
+
AgentToolKind,
|
|
63
|
+
AgentToolOutput,
|
|
64
|
+
AgentToolStarted,
|
|
65
|
+
AgentTurnFinished,
|
|
66
|
+
AgentTurnStarted,
|
|
67
|
+
AgentUsage,
|
|
68
|
+
AgentUserMessage,
|
|
43
69
|
ApiKey,
|
|
44
70
|
Backup,
|
|
45
71
|
BackupSchedule,
|
|
@@ -67,6 +93,7 @@ from .models import (
|
|
|
67
93
|
ExecResult,
|
|
68
94
|
SelfDeleteResult,
|
|
69
95
|
ExposedPort,
|
|
96
|
+
Harness,
|
|
70
97
|
BillingActivityEntry,
|
|
71
98
|
BillingActivityPage,
|
|
72
99
|
Machine,
|
|
@@ -168,6 +195,32 @@ __all__ = [
|
|
|
168
195
|
"OutputChunk",
|
|
169
196
|
# Models
|
|
170
197
|
"Account",
|
|
198
|
+
"AgentDelivery",
|
|
199
|
+
"AgentEvent",
|
|
200
|
+
"AgentEventBase",
|
|
201
|
+
"AgentFinishReason",
|
|
202
|
+
"AgentInterruptResult",
|
|
203
|
+
"AgentMessage",
|
|
204
|
+
"AgentMessageDelta",
|
|
205
|
+
"AgentPlan",
|
|
206
|
+
"AgentPlanItem",
|
|
207
|
+
"AgentRun",
|
|
208
|
+
"AgentRunStartedBy",
|
|
209
|
+
"AgentRunUsage",
|
|
210
|
+
"AgentRunsPage",
|
|
211
|
+
"AgentSendResult",
|
|
212
|
+
"AgentSendWhen",
|
|
213
|
+
"AgentSession",
|
|
214
|
+
"AgentSessionState",
|
|
215
|
+
"AgentThinkingDelta",
|
|
216
|
+
"AgentToolFinished",
|
|
217
|
+
"AgentToolKind",
|
|
218
|
+
"AgentToolOutput",
|
|
219
|
+
"AgentToolStarted",
|
|
220
|
+
"AgentTurnFinished",
|
|
221
|
+
"AgentTurnStarted",
|
|
222
|
+
"AgentUsage",
|
|
223
|
+
"AgentUserMessage",
|
|
171
224
|
"ApiKey",
|
|
172
225
|
"Backup",
|
|
173
226
|
"BackupSchedule",
|
|
@@ -195,6 +248,7 @@ __all__ = [
|
|
|
195
248
|
"FsEntryType",
|
|
196
249
|
"SelfDeleteResult",
|
|
197
250
|
"ExposedPort",
|
|
251
|
+
"Harness",
|
|
198
252
|
"BillingActivityEntry",
|
|
199
253
|
"BillingActivityPage",
|
|
200
254
|
"Machine",
|