archastro.platform.v1.resources.agent_computers

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 58d0acadaa0a
  4
  5from __future__ import annotations
  6
  7from typing import Required, TypedDict
  8
  9from ...runtime.http_client import HttpClient, SyncHttpClient
 10from ...types.common import AgentComputer
 11from ...types.computers import ComputerExecResult
 12
 13
 14class AgentComputerUpdateInputAclAddItem(TypedDict, total=False):
 15    actions: Required[list[str]]
 16    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 17    principal: str | None
 18    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 19    principal_type: Required[str]
 20    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 21
 22
 23class AgentComputerUpdateInputAclGrantsItem(TypedDict, total=False):
 24    actions: Required[list[str]]
 25    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 26    principal: str | None
 27    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 28    principal_type: Required[str]
 29    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 30
 31
 32class AgentComputerUpdateInputAclRemoveItem(TypedDict, total=False):
 33    principal: str | None
 34    'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.'
 35    principal_type: Required[str]
 36    'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 37
 38
 39class AgentComputerUpdateInputAcl(TypedDict, total=False):
 40    add: list[AgentComputerUpdateInputAclAddItem] | None
 41    "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`."
 42    grants: list[AgentComputerUpdateInputAclGrantsItem] | None
 43    "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`."
 44    remove: list[AgentComputerUpdateInputAclRemoveItem] | None
 45    "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
 46
 47
 48class AgentComputerUpdateInput(TypedDict, total=False):
 49    "Update a computer"
 50
 51    acl: AgentComputerUpdateInputAcl | None
 52    "Access control list replacement or add/remove operations."
 53
 54
 55class AgentComputerExecInput(TypedDict, total=False):
 56    "Execute a command on a computer"
 57
 58    command: Required[str]
 59    'Shell command to execute, e.g. `"ls -la /home"`.'
 60    dir: str | None
 61    "Absolute path to use as the working directory when executing the command. Defaults to the computer's home directory when omitted."
 62
 63
 64class AsyncAgentComputerResource:
 65    def __init__(self, http: HttpClient):
 66        self._http = http
 67
 68    async def delete(self, computer: str) -> None:
 69        """
 70        Delete a computer
 71        Permanently deletes the specified computer and releases all associated
 72        infrastructure resources. This action is irreversible once deleted,
 73        the computer cannot be recovered and its ID becomes invalid.
 74        Requires an app-scoped API key. The computer must belong to the same app.
 75        Returns `204 No Content` on success.
 76
 77        Args:
 78            computer: Computer ID (`cmp_...`). The computer to delete.
 79
 80        Returns:
 81            Empty response body. Returns HTTP 204 on success.
 82        """
 83        await self._http.request(f"/api/v1/agent_computers/{computer}", method="DELETE")
 84
 85    async def get(self, computer: str) -> AgentComputer:
 86        """
 87        Retrieve a computer
 88        Returns the computer identified by `computer`. The computer must belong to the
 89        app associated with the API key.
 90        Use this endpoint to inspect a computer's current `status`, `region`,
 91        `config`, and `metadata` after provisioning or to verify its state before
 92        issuing commands. For a live status update, use the refresh endpoint instead.
 93
 94        Args:
 95            computer: Computer ID (`cmp_...`). The computer to retrieve.
 96
 97        Returns:
 98            The requested computer.
 99        """
100        return await self._http.request(
101            f"/api/v1/agent_computers/{computer}",
102            response_type=AgentComputer,
103        )
104
105    async def update(self, computer: str, input: AgentComputerUpdateInput) -> None:
106        """
107        Update a computer
108        Updates the computer's direct access grants. Requires permission to modify
109        the computer. Read grants allow retrieval and command execution; write grants
110        also allow management and deletion. Use acl.grants to replace grants, or
111        acl.add/acl.remove to patch them. An empty acl.grants array revokes all direct
112        grants; omitting acl preserves them. Sharing does not add the computer to
113        agent or thread lists.
114
115        Args:
116            computer: Computer ID (`cmp_...`).
117            input: Request body.
118            input.acl: Access control list replacement or add/remove operations.
119
120        Returns:
121            Empty response body. Returns HTTP 204 on success.
122        """
123        await self._http.request(f"/api/v1/agent_computers/{computer}", method="PATCH", body=input)
124
125    async def exec(self, computer: str, input: AgentComputerExecInput) -> ComputerExecResult:
126        """
127        Execute a command on a computer
128        Runs a shell command on the specified computer and returns its combined
129        output and exit code. The call blocks until the command completes; there
130        is no streaming or timeout override plan accordingly for long-running
131        commands.
132        Requires an app-scoped API key. The computer must be in the `running`
133        state. Commands run as the default unprivileged user on the computer.
134        A non-zero `exit_code` in the response does not produce an HTTP error;
135        inspect `exit_code` and `output` to determine success.
136
137        Args:
138            computer: Computer ID (`cmp_...`). The computer on which to run the command.
139            input: Request body.
140            input.command: Shell command to execute, e.g. `"ls -la /home"`.
141            input.dir: Absolute path to use as the working directory when executing the command. Defaults to the computer's home directory when omitted.
142
143        Returns:
144            The output and exit code produced by the command.
145        """
146        return await self._http.request(
147            f"/api/v1/agent_computers/{computer}/exec",
148            method="POST",
149            body=input,
150            response_type=ComputerExecResult,
151        )
152
153    async def refresh(self, computer: str) -> AgentComputer:
154        """
155        Refresh a computer's status
156        Fetches the latest status for the specified computer from the upstream
157        provisioning provider and updates the platform record accordingly. Use this
158        endpoint to reconcile a computer whose `status` appears stale or stuck in
159        a transitional state such as `provisioning`.
160        Requires an app-scoped API key. Returns 422 if the computer has not been
161        fully provisioned yet. The updated computer object is returned on success.
162
163        Args:
164            computer: Computer ID (`cmp_...`). The computer whose status should be refreshed.
165
166        Returns:
167            The computer record with its status updated from the provisioning provider.
168        """
169        return await self._http.request(
170            f"/api/v1/agent_computers/{computer}/refresh",
171            method="POST",
172            response_type=AgentComputer,
173        )
174
175
176class AgentComputerResource:
177    def __init__(self, http: SyncHttpClient):
178        self._http = http
179
180    def delete(self, computer: str) -> None:
181        """
182        Delete a computer
183        Permanently deletes the specified computer and releases all associated
184        infrastructure resources. This action is irreversible once deleted,
185        the computer cannot be recovered and its ID becomes invalid.
186        Requires an app-scoped API key. The computer must belong to the same app.
187        Returns `204 No Content` on success.
188
189        Args:
190            computer: Computer ID (`cmp_...`). The computer to delete.
191
192        Returns:
193            Empty response body. Returns HTTP 204 on success.
194        """
195        self._http.request(f"/api/v1/agent_computers/{computer}", method="DELETE")
196
197    def get(self, computer: str) -> AgentComputer:
198        """
199        Retrieve a computer
200        Returns the computer identified by `computer`. The computer must belong to the
201        app associated with the API key.
202        Use this endpoint to inspect a computer's current `status`, `region`,
203        `config`, and `metadata` after provisioning or to verify its state before
204        issuing commands. For a live status update, use the refresh endpoint instead.
205
206        Args:
207            computer: Computer ID (`cmp_...`). The computer to retrieve.
208
209        Returns:
210            The requested computer.
211        """
212        return self._http.request(
213            f"/api/v1/agent_computers/{computer}",
214            response_type=AgentComputer,
215        )
216
217    def update(self, computer: str, input: AgentComputerUpdateInput) -> None:
218        """
219        Update a computer
220        Updates the computer's direct access grants. Requires permission to modify
221        the computer. Read grants allow retrieval and command execution; write grants
222        also allow management and deletion. Use acl.grants to replace grants, or
223        acl.add/acl.remove to patch them. An empty acl.grants array revokes all direct
224        grants; omitting acl preserves them. Sharing does not add the computer to
225        agent or thread lists.
226
227        Args:
228            computer: Computer ID (`cmp_...`).
229            input: Request body.
230            input.acl: Access control list replacement or add/remove operations.
231
232        Returns:
233            Empty response body. Returns HTTP 204 on success.
234        """
235        self._http.request(f"/api/v1/agent_computers/{computer}", method="PATCH", body=input)
236
237    def exec(self, computer: str, input: AgentComputerExecInput) -> ComputerExecResult:
238        """
239        Execute a command on a computer
240        Runs a shell command on the specified computer and returns its combined
241        output and exit code. The call blocks until the command completes; there
242        is no streaming or timeout override plan accordingly for long-running
243        commands.
244        Requires an app-scoped API key. The computer must be in the `running`
245        state. Commands run as the default unprivileged user on the computer.
246        A non-zero `exit_code` in the response does not produce an HTTP error;
247        inspect `exit_code` and `output` to determine success.
248
249        Args:
250            computer: Computer ID (`cmp_...`). The computer on which to run the command.
251            input: Request body.
252            input.command: Shell command to execute, e.g. `"ls -la /home"`.
253            input.dir: Absolute path to use as the working directory when executing the command. Defaults to the computer's home directory when omitted.
254
255        Returns:
256            The output and exit code produced by the command.
257        """
258        return self._http.request(
259            f"/api/v1/agent_computers/{computer}/exec",
260            method="POST",
261            body=input,
262            response_type=ComputerExecResult,
263        )
264
265    def refresh(self, computer: str) -> AgentComputer:
266        """
267        Refresh a computer's status
268        Fetches the latest status for the specified computer from the upstream
269        provisioning provider and updates the platform record accordingly. Use this
270        endpoint to reconcile a computer whose `status` appears stale or stuck in
271        a transitional state such as `provisioning`.
272        Requires an app-scoped API key. Returns 422 if the computer has not been
273        fully provisioned yet. The updated computer object is returned on success.
274
275        Args:
276            computer: Computer ID (`cmp_...`). The computer whose status should be refreshed.
277
278        Returns:
279            The computer record with its status updated from the provisioning provider.
280        """
281        return self._http.request(
282            f"/api/v1/agent_computers/{computer}/refresh",
283            method="POST",
284            response_type=AgentComputer,
285        )