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.
Files changed (61) hide show
  1. {boxd-0.3.2/src/boxd.egg-info → boxd-0.3.2.dev1182}/PKG-INFO +82 -1
  2. {boxd-0.3.2 → boxd-0.3.2.dev1182}/README.md +81 -0
  3. {boxd-0.3.2 → boxd-0.3.2.dev1182}/pyproject.toml +1 -1
  4. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/__init__.py +54 -0
  5. boxd-0.3.2.dev1182/src/boxd/_generated/api_pb2.py +816 -0
  6. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_generated/api_pb2_grpc.py +407 -0
  7. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_mappers.py +222 -0
  8. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_regions.py +5 -0
  9. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_requests.py +12 -0
  10. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/models.py +321 -1
  11. boxd-0.3.2.dev1182/src/boxd/resources/agents.py +615 -0
  12. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/machines.py +3 -0
  13. {boxd-0.3.2 → boxd-0.3.2.dev1182/src/boxd.egg-info}/PKG-INFO +82 -1
  14. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd.egg-info/SOURCES.txt +2 -0
  15. boxd-0.3.2.dev1182/tests/test_agents.py +921 -0
  16. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_regions.py +38 -0
  17. boxd-0.3.2/src/boxd/_generated/api_pb2.py +0 -740
  18. {boxd-0.3.2 → boxd-0.3.2.dev1182}/LICENSE +0 -0
  19. {boxd-0.3.2 → boxd-0.3.2.dev1182}/setup.cfg +0 -0
  20. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_client.py +0 -0
  21. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_credentials.py +0 -0
  22. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_generated/__init__.py +0 -0
  23. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_streaming.py +0 -0
  24. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_transport.py +0 -0
  25. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_urls.py +0 -0
  26. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/_version_check.py +0 -0
  27. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/computer_use.py +0 -0
  28. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/errors.py +0 -0
  29. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/py.typed +0 -0
  30. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/__init__.py +0 -0
  31. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/account.py +0 -0
  32. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/computer.py +0 -0
  33. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/credentials.py +0 -0
  34. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/disks.py +0 -0
  35. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/domains.py +0 -0
  36. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/fs.py +0 -0
  37. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/orgs.py +0 -0
  38. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/regions.py +0 -0
  39. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/snapshots.py +0 -0
  40. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/teams.py +0 -0
  41. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/resources/vars.py +0 -0
  42. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd/spec.py +0 -0
  43. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd.egg-info/dependency_links.txt +0 -0
  44. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd.egg-info/requires.txt +0 -0
  45. {boxd-0.3.2 → boxd-0.3.2.dev1182}/src/boxd.egg-info/top_level.txt +0 -0
  46. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_computer.py +0 -0
  47. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_computer_use.py +0 -0
  48. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_create_in_one_call.py +0 -0
  49. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_credentials.py +0 -0
  50. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_delete_self.py +0 -0
  51. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_fs.py +0 -0
  52. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_mappers.py +0 -0
  53. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_namespaces.py +0 -0
  54. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_python_versions.py +0 -0
  55. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_raw_key.py +0 -0
  56. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_requests.py +0 -0
  57. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_spec.py +0 -0
  58. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_streaming.py +0 -0
  59. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_transport.py +0 -0
  60. {boxd-0.3.2 → boxd-0.3.2.dev1182}/tests/test_urls.py +0 -0
  61. {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
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "boxd"
3
- version = "0.3.2"
3
+ version = "0.3.2.dev1182"
4
4
  description = "Python SDK for the boxd cloud VM platform"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -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",