archastro.platform.v1.resources.scripts 

  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: 9c57dd4942ea
  4
  5from __future__ import annotations
  6
  7from typing import Any, TypedDict
  8
  9from ...runtime.http_client import HttpClient, SyncHttpClient
 10from ...types.common import RuntimeEnvVarList
 11from ...types.expressions import ExpressionValidation
 12from ...types.scripts import ScriptLanguageSpec, ScriptRunResult, ScriptTestRunResult
 13
 14
 15class ScriptRunInput(TypedDict, total=False):
 16    "Execute a workflow script"
 17
 18    config: str | None
 19    "Stored Script config ID (`cfg_...`) whose current version is executed. Mutually exclusive with `script`. Required for server-side producers that must not supply raw source."
 20    config_key: str | None
 21    "`lookup_key` of an app-level Script config whose current version is executed. Resolved among the app's configs that belong to no organization, never an organization's config with the same key. Mutually exclusive with `script` and `config`."
 22    resolution_context_config: str | None
 23    "Optional Script config ID establishing the authorized installation context for imports."
 24    run_as_agent: str | None
 25    "Agent ID (`agt_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this agent. Mutually exclusive with `run_as_user`. `null` by default."
 26    run_as_user: str | None
 27    "User ID (`usr_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this user. Mutually exclusive with `run_as_agent`. `null` by default."
 28    scope: dict[str, Any] | None
 29    "Initial scope injected into the script execution context. Use this to supply `variables`, `system`, or other top-level scope keys."
 30    script: str | None
 31    "The script source to execute. Defaults to an empty string. Mutually exclusive with `config`."
 32    thread: str | None
 33    "Optional thread ID for agent execution. Requires run_as_agent, caller access to the thread, matching agent app and organization, and agent membership in the thread."
 34
 35
 36class ScriptTestInput(TypedDict, total=False):
 37    "Run a script test suite"
 38
 39    resolution_context_config: str | None
 40    "Optional config ID establishing the authorized installation context for imports."
 41    scope: dict[str, Any] | None
 42    "Optional overrides for the execution scope. Accepts `variables`, `system`, or other top-level scope keys."
 43    script: str | None
 44    "The test script source to execute. Should contain `describe` / `it` / `expect` blocks."
 45    scripts: dict[str, Any] | None
 46    'Optional map of local script sources keyed by lookup key (e.g. `"my_script"`). Used to resolve `import("script:<lookup_key>")` calls before falling back to deployed scripts in the caller\'s app.'
 47
 48
 49class ScriptValidateInput(TypedDict, total=False):
 50    "Validate a workflow script"
 51
 52    script: str | None
 53    "The script source to validate. Defaults to an empty string."
 54
 55
 56class AsyncScriptResource:
 57    def __init__(self, http: HttpClient):
 58        self._http = http
 59
 60    async def language(self) -> ScriptLanguageSpec:
 61        """
 62        Retrieve script language metadata
 63        Returns the full language specification for the ArchAstro scripting engine,
 64        including keywords, operators, built-in functions, namespaces, code snippets,
 65        and type system information.
 66        Use this response to power editor features such as syntax highlighting,
 67        autocompletion, hover documentation, and snippet insertion. The specification
 68        is static for a given platform version; you do not need to poll it on every
 69        session.
 70        Requires an authenticated viewer. No additional app scope is needed.
 71
 72        Returns:
 73            The script language specification for the current platform version.
 74        """
 75        return await self._http.request(
 76            "/api/v1/scripts/language",
 77            response_type=ScriptLanguageSpec,
 78        )
 79
 80    async def llm_txt(self) -> dict[str, str]:
 81        """
 82        Retrieve the script-authoring LLM prompt
 83        Returns the plain-text system prompt used by script-authoring assistants.
 84        The prompt is rendered from the current language specification so builtins,
 85        namespaces, snippets, and type-system guidance stay synchronized with the
 86        running platform.
 87
 88        Returns:
 89            Plain-text system prompt for script-authoring assistants.
 90        """
 91        return await self._http.request_raw("/api/v1/scripts/llm.txt")
 92
 93    async def run(self, input: ScriptRunInput) -> ScriptRunResult:
 94        """
 95        Execute a workflow script
 96        Executes script source and returns the result value together with any
 97        `print` output captured during the run. Pass `script` for interactive
 98        evaluation, or `config` to run a stored Script config by ID. Server-side
 99        producers (for example a webhook service emitting through `events.emit`)
100        must use `config`; raw source from those callers is not an authorized
101        application script.
102        The script runs with the authenticated viewer's identity by default. Org
103        targeting for secret-key callers comes from the `X-ArchAstro-Org-Id`
104        header, not from the body. Pass `run_as_user` to impersonate a specific
105        user, or `run_as_agent` to run as a specific agent, subject to the
106        caller's delegation permissions. These two params are mutually exclusive
107        supplying both returns a 422 error. `script` and `config` are also
108        mutually exclusive.
109        Runtime environment variables resolved for the execution identity's app and organization are automatically injected
110        into the script's `variables.env` scope. When the script raises a runtime
111        error, the response still returns HTTP 200 with `error`, `findings`, and any
112        partial output; the error is also recorded in the app's activity feed.
113
114        Args:
115            input: Request body.
116            input.config: Stored Script config ID (`cfg_...`) whose current version is executed. Mutually exclusive with `script`. Required for server-side producers that must not supply raw source.
117            input.config_key: `lookup_key` of an app-level Script config whose current version is executed. Resolved among the app's configs that belong to no organization, never an organization's config with the same key. Mutually exclusive with `script` and `config`.
118            input.resolution_context_config: Optional Script config ID establishing the authorized installation context for imports.
119            input.run_as_agent: Agent ID (`agt_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this agent. Mutually exclusive with `run_as_user`. `null` by default.
120            input.run_as_user: User ID (`usr_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this user. Mutually exclusive with `run_as_agent`. `null` by default.
121            input.scope: Initial scope injected into the script execution context. Use this to supply `variables`, `system`, or other top-level scope keys.
122            input.script: The script source to execute. Defaults to an empty string. Mutually exclusive with `config`.
123            input.thread: Optional thread ID for agent execution. Requires run_as_agent, caller access to the thread, matching agent app and organization, and agent membership in the thread.
124
125        Returns:
126            The script execution result, including the return value, captured output, and any runtime error or diagnostic findings.
127        """
128        return await self._http.request(
129            "/api/v1/scripts/run",
130            method="POST",
131            body=input,
132            response_type=ScriptRunResult,
133        )
134
135    async def runtime_env_vars(self) -> RuntimeEnvVarList:
136        """
137        List runtime environment variables for scripts
138        Returns metadata for all runtime environment variables available to scripts
139        running within the specified app. The response lists each variable's name
140        and description but does not include resolved values.
141        Use this to surface the available `env.*` identifiers in script editor
142        autocompletion or to inspect which variables are configured for an app
143        before running a script.
144        Requires an authenticated viewer scoped to the specified app.
145
146        Returns:
147            Paginated list of runtime environment variable metadata for the app.
148        """
149        return await self._http.request(
150            "/api/v1/scripts/runtime_env_vars",
151            response_type=RuntimeEnvVarList,
152        )
153
154    async def test(self, input: ScriptTestInput) -> ScriptTestRunResult:
155        """
156        Run a script test suite
157        Executes a Jest-style script test source (`describe` / `it` / `expect`) and
158        returns a structured assertion report. Use this endpoint to run unit tests
159        against script logic during development or in CI pipelines.
160        Imports of the form `import("script:<lookup_key>")` inside the test script
161        resolve against the `scripts` map supplied in the request body first, then
162        fall back to deployed scripts in the caller's app. This lets you test local
163        changes to scripts before deploying them.
164        Runtime environment variables defined for the app are automatically injected
165        into `variables.env` within the execution scope.
166        When a mid-run runtime error occurs (after some tests have already executed),
167        the endpoint returns HTTP 200 with `passed: false`, the partial per-test
168        breakdown, and a top-level `error` and `findings` describing the crash. When
169        the test source itself cannot be parsed, the endpoint returns HTTP 422 with
170        the syntax error message.
171
172        Args:
173            input: Request body.
174            input.resolution_context_config: Optional config ID establishing the authorized installation context for imports.
175            input.scope: Optional overrides for the execution scope. Accepts `variables`, `system`, or other top-level scope keys.
176            input.script: The test script source to execute. Should contain `describe` / `it` / `expect` blocks.
177            input.scripts: Optional map of local script sources keyed by lookup key (e.g. `"my_script"`). Used to resolve `import("script:<lookup_key>")` calls before falling back to deployed scripts in the caller's app.
178
179        Returns:
180            The assertion report for the test run, including per-suite and per-test results, assertion counts, captured output, and any runtime error or diagnostic findings.
181        """
182        return await self._http.request(
183            "/api/v1/scripts/test",
184            method="POST",
185            body=input,
186            response_type=ScriptTestRunResult,
187        )
188
189    async def validate(self, input: ScriptValidateInput) -> ExpressionValidation:
190        """
191        Validate a workflow script
192        Parses and statically analyzes the provided script source, returning a list
193        of diagnostic findings (errors and warnings) without executing the script.
194        Use this endpoint to power real-time syntax and type checking in script
195        editors.
196        The response always returns HTTP 200. Check the `findings` array in the
197        returned validation result for any errors or warnings. An empty `findings`
198        list means the script passed all static checks.
199        Requires an authenticated viewer. No additional app scope is needed.
200
201        Args:
202            input: Request body.
203            input.script: The script source to validate. Defaults to an empty string.
204
205        Returns:
206            Static analysis result containing a list of diagnostic findings for the script.
207        """
208        return await self._http.request(
209            "/api/v1/scripts/validate",
210            method="POST",
211            body=input,
212            response_type=ExpressionValidation,
213        )
214
215
216class ScriptResource:
217    def __init__(self, http: SyncHttpClient):
218        self._http = http
219
220    def language(self) -> ScriptLanguageSpec:
221        """
222        Retrieve script language metadata
223        Returns the full language specification for the ArchAstro scripting engine,
224        including keywords, operators, built-in functions, namespaces, code snippets,
225        and type system information.
226        Use this response to power editor features such as syntax highlighting,
227        autocompletion, hover documentation, and snippet insertion. The specification
228        is static for a given platform version; you do not need to poll it on every
229        session.
230        Requires an authenticated viewer. No additional app scope is needed.
231
232        Returns:
233            The script language specification for the current platform version.
234        """
235        return self._http.request("/api/v1/scripts/language", response_type=ScriptLanguageSpec)
236
237    def llm_txt(self) -> dict[str, str]:
238        """
239        Retrieve the script-authoring LLM prompt
240        Returns the plain-text system prompt used by script-authoring assistants.
241        The prompt is rendered from the current language specification so builtins,
242        namespaces, snippets, and type-system guidance stay synchronized with the
243        running platform.
244
245        Returns:
246            Plain-text system prompt for script-authoring assistants.
247        """
248        return self._http.request_raw("/api/v1/scripts/llm.txt")
249
250    def run(self, input: ScriptRunInput) -> ScriptRunResult:
251        """
252        Execute a workflow script
253        Executes script source and returns the result value together with any
254        `print` output captured during the run. Pass `script` for interactive
255        evaluation, or `config` to run a stored Script config by ID. Server-side
256        producers (for example a webhook service emitting through `events.emit`)
257        must use `config`; raw source from those callers is not an authorized
258        application script.
259        The script runs with the authenticated viewer's identity by default. Org
260        targeting for secret-key callers comes from the `X-ArchAstro-Org-Id`
261        header, not from the body. Pass `run_as_user` to impersonate a specific
262        user, or `run_as_agent` to run as a specific agent, subject to the
263        caller's delegation permissions. These two params are mutually exclusive
264        supplying both returns a 422 error. `script` and `config` are also
265        mutually exclusive.
266        Runtime environment variables resolved for the execution identity's app and organization are automatically injected
267        into the script's `variables.env` scope. When the script raises a runtime
268        error, the response still returns HTTP 200 with `error`, `findings`, and any
269        partial output; the error is also recorded in the app's activity feed.
270
271        Args:
272            input: Request body.
273            input.config: Stored Script config ID (`cfg_...`) whose current version is executed. Mutually exclusive with `script`. Required for server-side producers that must not supply raw source.
274            input.config_key: `lookup_key` of an app-level Script config whose current version is executed. Resolved among the app's configs that belong to no organization, never an organization's config with the same key. Mutually exclusive with `script` and `config`.
275            input.resolution_context_config: Optional Script config ID establishing the authorized installation context for imports.
276            input.run_as_agent: Agent ID (`agt_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this agent. Mutually exclusive with `run_as_user`. `null` by default.
277            input.run_as_user: User ID (`usr_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this user. Mutually exclusive with `run_as_agent`. `null` by default.
278            input.scope: Initial scope injected into the script execution context. Use this to supply `variables`, `system`, or other top-level scope keys.
279            input.script: The script source to execute. Defaults to an empty string. Mutually exclusive with `config`.
280            input.thread: Optional thread ID for agent execution. Requires run_as_agent, caller access to the thread, matching agent app and organization, and agent membership in the thread.
281
282        Returns:
283            The script execution result, including the return value, captured output, and any runtime error or diagnostic findings.
284        """
285        return self._http.request(
286            "/api/v1/scripts/run",
287            method="POST",
288            body=input,
289            response_type=ScriptRunResult,
290        )
291
292    def runtime_env_vars(self) -> RuntimeEnvVarList:
293        """
294        List runtime environment variables for scripts
295        Returns metadata for all runtime environment variables available to scripts
296        running within the specified app. The response lists each variable's name
297        and description but does not include resolved values.
298        Use this to surface the available `env.*` identifiers in script editor
299        autocompletion or to inspect which variables are configured for an app
300        before running a script.
301        Requires an authenticated viewer scoped to the specified app.
302
303        Returns:
304            Paginated list of runtime environment variable metadata for the app.
305        """
306        return self._http.request(
307            "/api/v1/scripts/runtime_env_vars",
308            response_type=RuntimeEnvVarList,
309        )
310
311    def test(self, input: ScriptTestInput) -> ScriptTestRunResult:
312        """
313        Run a script test suite
314        Executes a Jest-style script test source (`describe` / `it` / `expect`) and
315        returns a structured assertion report. Use this endpoint to run unit tests
316        against script logic during development or in CI pipelines.
317        Imports of the form `import("script:<lookup_key>")` inside the test script
318        resolve against the `scripts` map supplied in the request body first, then
319        fall back to deployed scripts in the caller's app. This lets you test local
320        changes to scripts before deploying them.
321        Runtime environment variables defined for the app are automatically injected
322        into `variables.env` within the execution scope.
323        When a mid-run runtime error occurs (after some tests have already executed),
324        the endpoint returns HTTP 200 with `passed: false`, the partial per-test
325        breakdown, and a top-level `error` and `findings` describing the crash. When
326        the test source itself cannot be parsed, the endpoint returns HTTP 422 with
327        the syntax error message.
328
329        Args:
330            input: Request body.
331            input.resolution_context_config: Optional config ID establishing the authorized installation context for imports.
332            input.scope: Optional overrides for the execution scope. Accepts `variables`, `system`, or other top-level scope keys.
333            input.script: The test script source to execute. Should contain `describe` / `it` / `expect` blocks.
334            input.scripts: Optional map of local script sources keyed by lookup key (e.g. `"my_script"`). Used to resolve `import("script:<lookup_key>")` calls before falling back to deployed scripts in the caller's app.
335
336        Returns:
337            The assertion report for the test run, including per-suite and per-test results, assertion counts, captured output, and any runtime error or diagnostic findings.
338        """
339        return self._http.request(
340            "/api/v1/scripts/test",
341            method="POST",
342            body=input,
343            response_type=ScriptTestRunResult,
344        )
345
346    def validate(self, input: ScriptValidateInput) -> ExpressionValidation:
347        """
348        Validate a workflow script
349        Parses and statically analyzes the provided script source, returning a list
350        of diagnostic findings (errors and warnings) without executing the script.
351        Use this endpoint to power real-time syntax and type checking in script
352        editors.
353        The response always returns HTTP 200. Check the `findings` array in the
354        returned validation result for any errors or warnings. An empty `findings`
355        list means the script passed all static checks.
356        Requires an authenticated viewer. No additional app scope is needed.
357
358        Args:
359            input: Request body.
360            input.script: The script source to validate. Defaults to an empty string.
361
362        Returns:
363            Static analysis result containing a list of diagnostic findings for the script.
364        """
365        return self._http.request(
366            "/api/v1/scripts/validate",
367            method="POST",
368            body=input,
369            response_type=ExpressionValidation,
370        )
class ScriptRunInput(typing.TypedDict): 
16class ScriptRunInput(TypedDict, total=False):
17    "Execute a workflow script"
18
19    config: str | None
20    "Stored Script config ID (`cfg_...`) whose current version is executed. Mutually exclusive with `script`. Required for server-side producers that must not supply raw source."
21    config_key: str | None
22    "`lookup_key` of an app-level Script config whose current version is executed. Resolved among the app's configs that belong to no organization, never an organization's config with the same key. Mutually exclusive with `script` and `config`."
23    resolution_context_config: str | None
24    "Optional Script config ID establishing the authorized installation context for imports."
25    run_as_agent: str | None
26    "Agent ID (`agt_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this agent. Mutually exclusive with `run_as_user`. `null` by default."
27    run_as_user: str | None
28    "User ID (`usr_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this user. Mutually exclusive with `run_as_agent`. `null` by default."
29    scope: dict[str, Any] | None
30    "Initial scope injected into the script execution context. Use this to supply `variables`, `system`, or other top-level scope keys."
31    script: str | None
32    "The script source to execute. Defaults to an empty string. Mutually exclusive with `config`."
33    thread: str | None
34    "Optional thread ID for agent execution. Requires run_as_agent, caller access to the thread, matching agent app and organization, and agent membership in the thread."

Execute a workflow script

config: str | None

Stored Script config ID (cfg_...) whose current version is executed. Mutually exclusive with script. Required for server-side producers that must not supply raw source.

config_key: str | None

lookup_key of an app-level Script config whose current version is executed. Resolved among the app's configs that belong to no organization, never an organization's config with the same key. Mutually exclusive with script and config.

resolution_context_config: str | None

Optional Script config ID establishing the authorized installation context for imports.

run_as_agent: str | None

Agent ID (agt_...) to impersonate during execution. When set, the script's system.viewer is replaced with a viewer for this agent. Mutually exclusive with run_as_user. null by default.

run_as_user: str | None

User ID (usr_...) to impersonate during execution. When set, the script's system.viewer is replaced with a viewer for this user. Mutually exclusive with run_as_agent. null by default.

scope: dict[str, typing.Any] | None

Initial scope injected into the script execution context. Use this to supply variables, system, or other top-level scope keys.

script: str | None

The script source to execute. Defaults to an empty string. Mutually exclusive with config.

thread: str | None

Optional thread ID for agent execution. Requires run_as_agent, caller access to the thread, matching agent app and organization, and agent membership in the thread.

class ScriptTestInput(typing.TypedDict): 
37class ScriptTestInput(TypedDict, total=False):
38    "Run a script test suite"
39
40    resolution_context_config: str | None
41    "Optional config ID establishing the authorized installation context for imports."
42    scope: dict[str, Any] | None
43    "Optional overrides for the execution scope. Accepts `variables`, `system`, or other top-level scope keys."
44    script: str | None
45    "The test script source to execute. Should contain `describe` / `it` / `expect` blocks."
46    scripts: dict[str, Any] | None
47    'Optional map of local script sources keyed by lookup key (e.g. `"my_script"`). Used to resolve `import("script:<lookup_key>")` calls before falling back to deployed scripts in the caller\'s app.'

Run a script test suite

resolution_context_config: str | None

Optional config ID establishing the authorized installation context for imports.

scope: dict[str, typing.Any] | None

Optional overrides for the execution scope. Accepts variables, system, or other top-level scope keys.

script: str | None

The test script source to execute. Should contain describe / it / expect blocks.

scripts: dict[str, typing.Any] | None

Optional map of local script sources keyed by lookup key (e.g. "my_script"). Used to resolve import("script:<lookup_key>") calls before falling back to deployed scripts in the caller's app.

class ScriptValidateInput(typing.TypedDict): 
50class ScriptValidateInput(TypedDict, total=False):
51    "Validate a workflow script"
52
53    script: str | None
54    "The script source to validate. Defaults to an empty string."

Validate a workflow script

script: str | None

The script source to validate. Defaults to an empty string.

class AsyncScriptResource: 
 57class AsyncScriptResource:
 58    def __init__(self, http: HttpClient):
 59        self._http = http
 60
 61    async def language(self) -> ScriptLanguageSpec:
 62        """
 63        Retrieve script language metadata
 64        Returns the full language specification for the ArchAstro scripting engine,
 65        including keywords, operators, built-in functions, namespaces, code snippets,
 66        and type system information.
 67        Use this response to power editor features such as syntax highlighting,
 68        autocompletion, hover documentation, and snippet insertion. The specification
 69        is static for a given platform version; you do not need to poll it on every
 70        session.
 71        Requires an authenticated viewer. No additional app scope is needed.
 72
 73        Returns:
 74            The script language specification for the current platform version.
 75        """
 76        return await self._http.request(
 77            "/api/v1/scripts/language",
 78            response_type=ScriptLanguageSpec,
 79        )
 80
 81    async def llm_txt(self) -> dict[str, str]:
 82        """
 83        Retrieve the script-authoring LLM prompt
 84        Returns the plain-text system prompt used by script-authoring assistants.
 85        The prompt is rendered from the current language specification so builtins,
 86        namespaces, snippets, and type-system guidance stay synchronized with the
 87        running platform.
 88
 89        Returns:
 90            Plain-text system prompt for script-authoring assistants.
 91        """
 92        return await self._http.request_raw("/api/v1/scripts/llm.txt")
 93
 94    async def run(self, input: ScriptRunInput) -> ScriptRunResult:
 95        """
 96        Execute a workflow script
 97        Executes script source and returns the result value together with any
 98        `print` output captured during the run. Pass `script` for interactive
 99        evaluation, or `config` to run a stored Script config by ID. Server-side
100        producers (for example a webhook service emitting through `events.emit`)
101        must use `config`; raw source from those callers is not an authorized
102        application script.
103        The script runs with the authenticated viewer's identity by default. Org
104        targeting for secret-key callers comes from the `X-ArchAstro-Org-Id`
105        header, not from the body. Pass `run_as_user` to impersonate a specific
106        user, or `run_as_agent` to run as a specific agent, subject to the
107        caller's delegation permissions. These two params are mutually exclusive
108        supplying both returns a 422 error. `script` and `config` are also
109        mutually exclusive.
110        Runtime environment variables resolved for the execution identity's app and organization are automatically injected
111        into the script's `variables.env` scope. When the script raises a runtime
112        error, the response still returns HTTP 200 with `error`, `findings`, and any
113        partial output; the error is also recorded in the app's activity feed.
114
115        Args:
116            input: Request body.
117            input.config: Stored Script config ID (`cfg_...`) whose current version is executed. Mutually exclusive with `script`. Required for server-side producers that must not supply raw source.
118            input.config_key: `lookup_key` of an app-level Script config whose current version is executed. Resolved among the app's configs that belong to no organization, never an organization's config with the same key. Mutually exclusive with `script` and `config`.
119            input.resolution_context_config: Optional Script config ID establishing the authorized installation context for imports.
120            input.run_as_agent: Agent ID (`agt_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this agent. Mutually exclusive with `run_as_user`. `null` by default.
121            input.run_as_user: User ID (`usr_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this user. Mutually exclusive with `run_as_agent`. `null` by default.
122            input.scope: Initial scope injected into the script execution context. Use this to supply `variables`, `system`, or other top-level scope keys.
123            input.script: The script source to execute. Defaults to an empty string. Mutually exclusive with `config`.
124            input.thread: Optional thread ID for agent execution. Requires run_as_agent, caller access to the thread, matching agent app and organization, and agent membership in the thread.
125
126        Returns:
127            The script execution result, including the return value, captured output, and any runtime error or diagnostic findings.
128        """
129        return await self._http.request(
130            "/api/v1/scripts/run",
131            method="POST",
132            body=input,
133            response_type=ScriptRunResult,
134        )
135
136    async def runtime_env_vars(self) -> RuntimeEnvVarList:
137        """
138        List runtime environment variables for scripts
139        Returns metadata for all runtime environment variables available to scripts
140        running within the specified app. The response lists each variable's name
141        and description but does not include resolved values.
142        Use this to surface the available `env.*` identifiers in script editor
143        autocompletion or to inspect which variables are configured for an app
144        before running a script.
145        Requires an authenticated viewer scoped to the specified app.
146
147        Returns:
148            Paginated list of runtime environment variable metadata for the app.
149        """
150        return await self._http.request(
151            "/api/v1/scripts/runtime_env_vars",
152            response_type=RuntimeEnvVarList,
153        )
154
155    async def test(self, input: ScriptTestInput) -> ScriptTestRunResult:
156        """
157        Run a script test suite
158        Executes a Jest-style script test source (`describe` / `it` / `expect`) and
159        returns a structured assertion report. Use this endpoint to run unit tests
160        against script logic during development or in CI pipelines.
161        Imports of the form `import("script:<lookup_key>")` inside the test script
162        resolve against the `scripts` map supplied in the request body first, then
163        fall back to deployed scripts in the caller's app. This lets you test local
164        changes to scripts before deploying them.
165        Runtime environment variables defined for the app are automatically injected
166        into `variables.env` within the execution scope.
167        When a mid-run runtime error occurs (after some tests have already executed),
168        the endpoint returns HTTP 200 with `passed: false`, the partial per-test
169        breakdown, and a top-level `error` and `findings` describing the crash. When
170        the test source itself cannot be parsed, the endpoint returns HTTP 422 with
171        the syntax error message.
172
173        Args:
174            input: Request body.
175            input.resolution_context_config: Optional config ID establishing the authorized installation context for imports.
176            input.scope: Optional overrides for the execution scope. Accepts `variables`, `system`, or other top-level scope keys.
177            input.script: The test script source to execute. Should contain `describe` / `it` / `expect` blocks.
178            input.scripts: Optional map of local script sources keyed by lookup key (e.g. `"my_script"`). Used to resolve `import("script:<lookup_key>")` calls before falling back to deployed scripts in the caller's app.
179
180        Returns:
181            The assertion report for the test run, including per-suite and per-test results, assertion counts, captured output, and any runtime error or diagnostic findings.
182        """
183        return await self._http.request(
184            "/api/v1/scripts/test",
185            method="POST",
186            body=input,
187            response_type=ScriptTestRunResult,
188        )
189
190    async def validate(self, input: ScriptValidateInput) -> ExpressionValidation:
191        """
192        Validate a workflow script
193        Parses and statically analyzes the provided script source, returning a list
194        of diagnostic findings (errors and warnings) without executing the script.
195        Use this endpoint to power real-time syntax and type checking in script
196        editors.
197        The response always returns HTTP 200. Check the `findings` array in the
198        returned validation result for any errors or warnings. An empty `findings`
199        list means the script passed all static checks.
200        Requires an authenticated viewer. No additional app scope is needed.
201
202        Args:
203            input: Request body.
204            input.script: The script source to validate. Defaults to an empty string.
205
206        Returns:
207            Static analysis result containing a list of diagnostic findings for the script.
208        """
209        return await self._http.request(
210            "/api/v1/scripts/validate",
211            method="POST",
212            body=input,
213            response_type=ExpressionValidation,
214        )
AsyncScriptResource(http: archastro.platform.runtime.http_client.HttpClient) 
58    def __init__(self, http: HttpClient):
59        self._http = http
async def language(self) -> archastro.platform.types.scripts.ScriptLanguageSpec: 
61    async def language(self) -> ScriptLanguageSpec:
62        """
63        Retrieve script language metadata
64        Returns the full language specification for the ArchAstro scripting engine,
65        including keywords, operators, built-in functions, namespaces, code snippets,
66        and type system information.
67        Use this response to power editor features such as syntax highlighting,
68        autocompletion, hover documentation, and snippet insertion. The specification
69        is static for a given platform version; you do not need to poll it on every
70        session.
71        Requires an authenticated viewer. No additional app scope is needed.
72
73        Returns:
74            The script language specification for the current platform version.
75        """
76        return await self._http.request(
77            "/api/v1/scripts/language",
78            response_type=ScriptLanguageSpec,
79        )

Retrieve script language metadata Returns the full language specification for the ArchAstro scripting engine, including keywords, operators, built-in functions, namespaces, code snippets, and type system information. Use this response to power editor features such as syntax highlighting, autocompletion, hover documentation, and snippet insertion. The specification is static for a given platform version; you do not need to poll it on every session. Requires an authenticated viewer. No additional app scope is needed.

Returns:

The script language specification for the current platform version.

async def llm_txt(self) -> dict[str, str]: 
81    async def llm_txt(self) -> dict[str, str]:
82        """
83        Retrieve the script-authoring LLM prompt
84        Returns the plain-text system prompt used by script-authoring assistants.
85        The prompt is rendered from the current language specification so builtins,
86        namespaces, snippets, and type-system guidance stay synchronized with the
87        running platform.
88
89        Returns:
90            Plain-text system prompt for script-authoring assistants.
91        """
92        return await self._http.request_raw("/api/v1/scripts/llm.txt")

Retrieve the script-authoring LLM prompt Returns the plain-text system prompt used by script-authoring assistants. The prompt is rendered from the current language specification so builtins, namespaces, snippets, and type-system guidance stay synchronized with the running platform.

Returns:

Plain-text system prompt for script-authoring assistants.

async def run( self, input: ScriptRunInput) -> archastro.platform.types.scripts.ScriptRunResult: 
 94    async def run(self, input: ScriptRunInput) -> ScriptRunResult:
 95        """
 96        Execute a workflow script
 97        Executes script source and returns the result value together with any
 98        `print` output captured during the run. Pass `script` for interactive
 99        evaluation, or `config` to run a stored Script config by ID. Server-side
100        producers (for example a webhook service emitting through `events.emit`)
101        must use `config`; raw source from those callers is not an authorized
102        application script.
103        The script runs with the authenticated viewer's identity by default. Org
104        targeting for secret-key callers comes from the `X-ArchAstro-Org-Id`
105        header, not from the body. Pass `run_as_user` to impersonate a specific
106        user, or `run_as_agent` to run as a specific agent, subject to the
107        caller's delegation permissions. These two params are mutually exclusive
108        supplying both returns a 422 error. `script` and `config` are also
109        mutually exclusive.
110        Runtime environment variables resolved for the execution identity's app and organization are automatically injected
111        into the script's `variables.env` scope. When the script raises a runtime
112        error, the response still returns HTTP 200 with `error`, `findings`, and any
113        partial output; the error is also recorded in the app's activity feed.
114
115        Args:
116            input: Request body.
117            input.config: Stored Script config ID (`cfg_...`) whose current version is executed. Mutually exclusive with `script`. Required for server-side producers that must not supply raw source.
118            input.config_key: `lookup_key` of an app-level Script config whose current version is executed. Resolved among the app's configs that belong to no organization, never an organization's config with the same key. Mutually exclusive with `script` and `config`.
119            input.resolution_context_config: Optional Script config ID establishing the authorized installation context for imports.
120            input.run_as_agent: Agent ID (`agt_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this agent. Mutually exclusive with `run_as_user`. `null` by default.
121            input.run_as_user: User ID (`usr_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this user. Mutually exclusive with `run_as_agent`. `null` by default.
122            input.scope: Initial scope injected into the script execution context. Use this to supply `variables`, `system`, or other top-level scope keys.
123            input.script: The script source to execute. Defaults to an empty string. Mutually exclusive with `config`.
124            input.thread: Optional thread ID for agent execution. Requires run_as_agent, caller access to the thread, matching agent app and organization, and agent membership in the thread.
125
126        Returns:
127            The script execution result, including the return value, captured output, and any runtime error or diagnostic findings.
128        """
129        return await self._http.request(
130            "/api/v1/scripts/run",
131            method="POST",
132            body=input,
133            response_type=ScriptRunResult,
134        )

Execute a workflow script Executes script source and returns the result value together with any print output captured during the run. Pass script for interactive evaluation, or config to run a stored Script config by ID. Server-side producers (for example a webhook service emitting through events.emit) must use config; raw source from those callers is not an authorized application script. The script runs with the authenticated viewer's identity by default. Org targeting for secret-key callers comes from the X-ArchAstro-Org-Id header, not from the body. Pass run_as_user to impersonate a specific user, or run_as_agent to run as a specific agent, subject to the caller's delegation permissions. These two params are mutually exclusive supplying both returns a 422 error. script and config are also mutually exclusive. Runtime environment variables resolved for the execution identity's app and organization are automatically injected into the script's variables.env scope. When the script raises a runtime error, the response still returns HTTP 200 with error, findings, and any partial output; the error is also recorded in the app's activity feed.

Arguments:
  • input: Request body.
  • input.config: Stored Script config ID (cfg_...) whose current version is executed. Mutually exclusive with script. Required for server-side producers that must not supply raw source.
  • input.config_key: lookup_key of an app-level Script config whose current version is executed. Resolved among the app's configs that belong to no organization, never an organization's config with the same key. Mutually exclusive with script and config.
  • input.resolution_context_config: Optional Script config ID establishing the authorized installation context for imports.
  • input.run_as_agent: Agent ID (agt_...) to impersonate during execution. When set, the script's system.viewer is replaced with a viewer for this agent. Mutually exclusive with run_as_user. null by default.
  • input.run_as_user: User ID (usr_...) to impersonate during execution. When set, the script's system.viewer is replaced with a viewer for this user. Mutually exclusive with run_as_agent. null by default.
  • input.scope: Initial scope injected into the script execution context. Use this to supply variables, system, or other top-level scope keys.
  • input.script: The script source to execute. Defaults to an empty string. Mutually exclusive with config.
  • input.thread: Optional thread ID for agent execution. Requires run_as_agent, caller access to the thread, matching agent app and organization, and agent membership in the thread.
Returns:

The script execution result, including the return value, captured output, and any runtime error or diagnostic findings.

async def runtime_env_vars(self) -> archastro.platform.types.common.RuntimeEnvVarList: 
136    async def runtime_env_vars(self) -> RuntimeEnvVarList:
137        """
138        List runtime environment variables for scripts
139        Returns metadata for all runtime environment variables available to scripts
140        running within the specified app. The response lists each variable's name
141        and description but does not include resolved values.
142        Use this to surface the available `env.*` identifiers in script editor
143        autocompletion or to inspect which variables are configured for an app
144        before running a script.
145        Requires an authenticated viewer scoped to the specified app.
146
147        Returns:
148            Paginated list of runtime environment variable metadata for the app.
149        """
150        return await self._http.request(
151            "/api/v1/scripts/runtime_env_vars",
152            response_type=RuntimeEnvVarList,
153        )

List runtime environment variables for scripts Returns metadata for all runtime environment variables available to scripts running within the specified app. The response lists each variable's name and description but does not include resolved values. Use this to surface the available env.* identifiers in script editor autocompletion or to inspect which variables are configured for an app before running a script. Requires an authenticated viewer scoped to the specified app.

Returns:

Paginated list of runtime environment variable metadata for the app.

async def test( self, input: ScriptTestInput) -> archastro.platform.types.scripts.ScriptTestRunResult: 
155    async def test(self, input: ScriptTestInput) -> ScriptTestRunResult:
156        """
157        Run a script test suite
158        Executes a Jest-style script test source (`describe` / `it` / `expect`) and
159        returns a structured assertion report. Use this endpoint to run unit tests
160        against script logic during development or in CI pipelines.
161        Imports of the form `import("script:<lookup_key>")` inside the test script
162        resolve against the `scripts` map supplied in the request body first, then
163        fall back to deployed scripts in the caller's app. This lets you test local
164        changes to scripts before deploying them.
165        Runtime environment variables defined for the app are automatically injected
166        into `variables.env` within the execution scope.
167        When a mid-run runtime error occurs (after some tests have already executed),
168        the endpoint returns HTTP 200 with `passed: false`, the partial per-test
169        breakdown, and a top-level `error` and `findings` describing the crash. When
170        the test source itself cannot be parsed, the endpoint returns HTTP 422 with
171        the syntax error message.
172
173        Args:
174            input: Request body.
175            input.resolution_context_config: Optional config ID establishing the authorized installation context for imports.
176            input.scope: Optional overrides for the execution scope. Accepts `variables`, `system`, or other top-level scope keys.
177            input.script: The test script source to execute. Should contain `describe` / `it` / `expect` blocks.
178            input.scripts: Optional map of local script sources keyed by lookup key (e.g. `"my_script"`). Used to resolve `import("script:<lookup_key>")` calls before falling back to deployed scripts in the caller's app.
179
180        Returns:
181            The assertion report for the test run, including per-suite and per-test results, assertion counts, captured output, and any runtime error or diagnostic findings.
182        """
183        return await self._http.request(
184            "/api/v1/scripts/test",
185            method="POST",
186            body=input,
187            response_type=ScriptTestRunResult,
188        )

Run a script test suite Executes a Jest-style script test source (describe / it / expect) and returns a structured assertion report. Use this endpoint to run unit tests against script logic during development or in CI pipelines. Imports of the form import("script:<lookup_key>") inside the test script resolve against the scripts map supplied in the request body first, then fall back to deployed scripts in the caller's app. This lets you test local changes to scripts before deploying them. Runtime environment variables defined for the app are automatically injected into variables.env within the execution scope. When a mid-run runtime error occurs (after some tests have already executed), the endpoint returns HTTP 200 with passed: false, the partial per-test breakdown, and a top-level error and findings describing the crash. When the test source itself cannot be parsed, the endpoint returns HTTP 422 with the syntax error message.

Arguments:
  • input: Request body.
  • input.resolution_context_config: Optional config ID establishing the authorized installation context for imports.
  • input.scope: Optional overrides for the execution scope. Accepts variables, system, or other top-level scope keys.
  • input.script: The test script source to execute. Should contain describe / it / expect blocks.
  • input.scripts: Optional map of local script sources keyed by lookup key (e.g. "my_script"). Used to resolve import("script:<lookup_key>") calls before falling back to deployed scripts in the caller's app.
Returns:

The assertion report for the test run, including per-suite and per-test results, assertion counts, captured output, and any runtime error or diagnostic findings.

async def validate( self, input: ScriptValidateInput) -> archastro.platform.types.expressions.ExpressionValidation: 
190    async def validate(self, input: ScriptValidateInput) -> ExpressionValidation:
191        """
192        Validate a workflow script
193        Parses and statically analyzes the provided script source, returning a list
194        of diagnostic findings (errors and warnings) without executing the script.
195        Use this endpoint to power real-time syntax and type checking in script
196        editors.
197        The response always returns HTTP 200. Check the `findings` array in the
198        returned validation result for any errors or warnings. An empty `findings`
199        list means the script passed all static checks.
200        Requires an authenticated viewer. No additional app scope is needed.
201
202        Args:
203            input: Request body.
204            input.script: The script source to validate. Defaults to an empty string.
205
206        Returns:
207            Static analysis result containing a list of diagnostic findings for the script.
208        """
209        return await self._http.request(
210            "/api/v1/scripts/validate",
211            method="POST",
212            body=input,
213            response_type=ExpressionValidation,
214        )

Validate a workflow script Parses and statically analyzes the provided script source, returning a list of diagnostic findings (errors and warnings) without executing the script. Use this endpoint to power real-time syntax and type checking in script editors. The response always returns HTTP 200. Check the findings array in the returned validation result for any errors or warnings. An empty findings list means the script passed all static checks. Requires an authenticated viewer. No additional app scope is needed.

Arguments:
  • input: Request body.
  • input.script: The script source to validate. Defaults to an empty string.
Returns:

Static analysis result containing a list of diagnostic findings for the script.

class ScriptResource: 
217class ScriptResource:
218    def __init__(self, http: SyncHttpClient):
219        self._http = http
220
221    def language(self) -> ScriptLanguageSpec:
222        """
223        Retrieve script language metadata
224        Returns the full language specification for the ArchAstro scripting engine,
225        including keywords, operators, built-in functions, namespaces, code snippets,
226        and type system information.
227        Use this response to power editor features such as syntax highlighting,
228        autocompletion, hover documentation, and snippet insertion. The specification
229        is static for a given platform version; you do not need to poll it on every
230        session.
231        Requires an authenticated viewer. No additional app scope is needed.
232
233        Returns:
234            The script language specification for the current platform version.
235        """
236        return self._http.request("/api/v1/scripts/language", response_type=ScriptLanguageSpec)
237
238    def llm_txt(self) -> dict[str, str]:
239        """
240        Retrieve the script-authoring LLM prompt
241        Returns the plain-text system prompt used by script-authoring assistants.
242        The prompt is rendered from the current language specification so builtins,
243        namespaces, snippets, and type-system guidance stay synchronized with the
244        running platform.
245
246        Returns:
247            Plain-text system prompt for script-authoring assistants.
248        """
249        return self._http.request_raw("/api/v1/scripts/llm.txt")
250
251    def run(self, input: ScriptRunInput) -> ScriptRunResult:
252        """
253        Execute a workflow script
254        Executes script source and returns the result value together with any
255        `print` output captured during the run. Pass `script` for interactive
256        evaluation, or `config` to run a stored Script config by ID. Server-side
257        producers (for example a webhook service emitting through `events.emit`)
258        must use `config`; raw source from those callers is not an authorized
259        application script.
260        The script runs with the authenticated viewer's identity by default. Org
261        targeting for secret-key callers comes from the `X-ArchAstro-Org-Id`
262        header, not from the body. Pass `run_as_user` to impersonate a specific
263        user, or `run_as_agent` to run as a specific agent, subject to the
264        caller's delegation permissions. These two params are mutually exclusive
265        supplying both returns a 422 error. `script` and `config` are also
266        mutually exclusive.
267        Runtime environment variables resolved for the execution identity's app and organization are automatically injected
268        into the script's `variables.env` scope. When the script raises a runtime
269        error, the response still returns HTTP 200 with `error`, `findings`, and any
270        partial output; the error is also recorded in the app's activity feed.
271
272        Args:
273            input: Request body.
274            input.config: Stored Script config ID (`cfg_...`) whose current version is executed. Mutually exclusive with `script`. Required for server-side producers that must not supply raw source.
275            input.config_key: `lookup_key` of an app-level Script config whose current version is executed. Resolved among the app's configs that belong to no organization, never an organization's config with the same key. Mutually exclusive with `script` and `config`.
276            input.resolution_context_config: Optional Script config ID establishing the authorized installation context for imports.
277            input.run_as_agent: Agent ID (`agt_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this agent. Mutually exclusive with `run_as_user`. `null` by default.
278            input.run_as_user: User ID (`usr_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this user. Mutually exclusive with `run_as_agent`. `null` by default.
279            input.scope: Initial scope injected into the script execution context. Use this to supply `variables`, `system`, or other top-level scope keys.
280            input.script: The script source to execute. Defaults to an empty string. Mutually exclusive with `config`.
281            input.thread: Optional thread ID for agent execution. Requires run_as_agent, caller access to the thread, matching agent app and organization, and agent membership in the thread.
282
283        Returns:
284            The script execution result, including the return value, captured output, and any runtime error or diagnostic findings.
285        """
286        return self._http.request(
287            "/api/v1/scripts/run",
288            method="POST",
289            body=input,
290            response_type=ScriptRunResult,
291        )
292
293    def runtime_env_vars(self) -> RuntimeEnvVarList:
294        """
295        List runtime environment variables for scripts
296        Returns metadata for all runtime environment variables available to scripts
297        running within the specified app. The response lists each variable's name
298        and description but does not include resolved values.
299        Use this to surface the available `env.*` identifiers in script editor
300        autocompletion or to inspect which variables are configured for an app
301        before running a script.
302        Requires an authenticated viewer scoped to the specified app.
303
304        Returns:
305            Paginated list of runtime environment variable metadata for the app.
306        """
307        return self._http.request(
308            "/api/v1/scripts/runtime_env_vars",
309            response_type=RuntimeEnvVarList,
310        )
311
312    def test(self, input: ScriptTestInput) -> ScriptTestRunResult:
313        """
314        Run a script test suite
315        Executes a Jest-style script test source (`describe` / `it` / `expect`) and
316        returns a structured assertion report. Use this endpoint to run unit tests
317        against script logic during development or in CI pipelines.
318        Imports of the form `import("script:<lookup_key>")` inside the test script
319        resolve against the `scripts` map supplied in the request body first, then
320        fall back to deployed scripts in the caller's app. This lets you test local
321        changes to scripts before deploying them.
322        Runtime environment variables defined for the app are automatically injected
323        into `variables.env` within the execution scope.
324        When a mid-run runtime error occurs (after some tests have already executed),
325        the endpoint returns HTTP 200 with `passed: false`, the partial per-test
326        breakdown, and a top-level `error` and `findings` describing the crash. When
327        the test source itself cannot be parsed, the endpoint returns HTTP 422 with
328        the syntax error message.
329
330        Args:
331            input: Request body.
332            input.resolution_context_config: Optional config ID establishing the authorized installation context for imports.
333            input.scope: Optional overrides for the execution scope. Accepts `variables`, `system`, or other top-level scope keys.
334            input.script: The test script source to execute. Should contain `describe` / `it` / `expect` blocks.
335            input.scripts: Optional map of local script sources keyed by lookup key (e.g. `"my_script"`). Used to resolve `import("script:<lookup_key>")` calls before falling back to deployed scripts in the caller's app.
336
337        Returns:
338            The assertion report for the test run, including per-suite and per-test results, assertion counts, captured output, and any runtime error or diagnostic findings.
339        """
340        return self._http.request(
341            "/api/v1/scripts/test",
342            method="POST",
343            body=input,
344            response_type=ScriptTestRunResult,
345        )
346
347    def validate(self, input: ScriptValidateInput) -> ExpressionValidation:
348        """
349        Validate a workflow script
350        Parses and statically analyzes the provided script source, returning a list
351        of diagnostic findings (errors and warnings) without executing the script.
352        Use this endpoint to power real-time syntax and type checking in script
353        editors.
354        The response always returns HTTP 200. Check the `findings` array in the
355        returned validation result for any errors or warnings. An empty `findings`
356        list means the script passed all static checks.
357        Requires an authenticated viewer. No additional app scope is needed.
358
359        Args:
360            input: Request body.
361            input.script: The script source to validate. Defaults to an empty string.
362
363        Returns:
364            Static analysis result containing a list of diagnostic findings for the script.
365        """
366        return self._http.request(
367            "/api/v1/scripts/validate",
368            method="POST",
369            body=input,
370            response_type=ExpressionValidation,
371        )
ScriptResource(http: archastro.platform.runtime.http_client.SyncHttpClient) 
218    def __init__(self, http: SyncHttpClient):
219        self._http = http
def language(self) -> archastro.platform.types.scripts.ScriptLanguageSpec: 
221    def language(self) -> ScriptLanguageSpec:
222        """
223        Retrieve script language metadata
224        Returns the full language specification for the ArchAstro scripting engine,
225        including keywords, operators, built-in functions, namespaces, code snippets,
226        and type system information.
227        Use this response to power editor features such as syntax highlighting,
228        autocompletion, hover documentation, and snippet insertion. The specification
229        is static for a given platform version; you do not need to poll it on every
230        session.
231        Requires an authenticated viewer. No additional app scope is needed.
232
233        Returns:
234            The script language specification for the current platform version.
235        """
236        return self._http.request("/api/v1/scripts/language", response_type=ScriptLanguageSpec)

Retrieve script language metadata Returns the full language specification for the ArchAstro scripting engine, including keywords, operators, built-in functions, namespaces, code snippets, and type system information. Use this response to power editor features such as syntax highlighting, autocompletion, hover documentation, and snippet insertion. The specification is static for a given platform version; you do not need to poll it on every session. Requires an authenticated viewer. No additional app scope is needed.

Returns:

The script language specification for the current platform version.

def llm_txt(self) -> dict[str, str]: 
238    def llm_txt(self) -> dict[str, str]:
239        """
240        Retrieve the script-authoring LLM prompt
241        Returns the plain-text system prompt used by script-authoring assistants.
242        The prompt is rendered from the current language specification so builtins,
243        namespaces, snippets, and type-system guidance stay synchronized with the
244        running platform.
245
246        Returns:
247            Plain-text system prompt for script-authoring assistants.
248        """
249        return self._http.request_raw("/api/v1/scripts/llm.txt")

Retrieve the script-authoring LLM prompt Returns the plain-text system prompt used by script-authoring assistants. The prompt is rendered from the current language specification so builtins, namespaces, snippets, and type-system guidance stay synchronized with the running platform.

Returns:

Plain-text system prompt for script-authoring assistants.

def run( self, input: ScriptRunInput) -> archastro.platform.types.scripts.ScriptRunResult: 
251    def run(self, input: ScriptRunInput) -> ScriptRunResult:
252        """
253        Execute a workflow script
254        Executes script source and returns the result value together with any
255        `print` output captured during the run. Pass `script` for interactive
256        evaluation, or `config` to run a stored Script config by ID. Server-side
257        producers (for example a webhook service emitting through `events.emit`)
258        must use `config`; raw source from those callers is not an authorized
259        application script.
260        The script runs with the authenticated viewer's identity by default. Org
261        targeting for secret-key callers comes from the `X-ArchAstro-Org-Id`
262        header, not from the body. Pass `run_as_user` to impersonate a specific
263        user, or `run_as_agent` to run as a specific agent, subject to the
264        caller's delegation permissions. These two params are mutually exclusive
265        supplying both returns a 422 error. `script` and `config` are also
266        mutually exclusive.
267        Runtime environment variables resolved for the execution identity's app and organization are automatically injected
268        into the script's `variables.env` scope. When the script raises a runtime
269        error, the response still returns HTTP 200 with `error`, `findings`, and any
270        partial output; the error is also recorded in the app's activity feed.
271
272        Args:
273            input: Request body.
274            input.config: Stored Script config ID (`cfg_...`) whose current version is executed. Mutually exclusive with `script`. Required for server-side producers that must not supply raw source.
275            input.config_key: `lookup_key` of an app-level Script config whose current version is executed. Resolved among the app's configs that belong to no organization, never an organization's config with the same key. Mutually exclusive with `script` and `config`.
276            input.resolution_context_config: Optional Script config ID establishing the authorized installation context for imports.
277            input.run_as_agent: Agent ID (`agt_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this agent. Mutually exclusive with `run_as_user`. `null` by default.
278            input.run_as_user: User ID (`usr_...`) to impersonate during execution. When set, the script's `system.viewer` is replaced with a viewer for this user. Mutually exclusive with `run_as_agent`. `null` by default.
279            input.scope: Initial scope injected into the script execution context. Use this to supply `variables`, `system`, or other top-level scope keys.
280            input.script: The script source to execute. Defaults to an empty string. Mutually exclusive with `config`.
281            input.thread: Optional thread ID for agent execution. Requires run_as_agent, caller access to the thread, matching agent app and organization, and agent membership in the thread.
282
283        Returns:
284            The script execution result, including the return value, captured output, and any runtime error or diagnostic findings.
285        """
286        return self._http.request(
287            "/api/v1/scripts/run",
288            method="POST",
289            body=input,
290            response_type=ScriptRunResult,
291        )

Execute a workflow script Executes script source and returns the result value together with any print output captured during the run. Pass script for interactive evaluation, or config to run a stored Script config by ID. Server-side producers (for example a webhook service emitting through events.emit) must use config; raw source from those callers is not an authorized application script. The script runs with the authenticated viewer's identity by default. Org targeting for secret-key callers comes from the X-ArchAstro-Org-Id header, not from the body. Pass run_as_user to impersonate a specific user, or run_as_agent to run as a specific agent, subject to the caller's delegation permissions. These two params are mutually exclusive supplying both returns a 422 error. script and config are also mutually exclusive. Runtime environment variables resolved for the execution identity's app and organization are automatically injected into the script's variables.env scope. When the script raises a runtime error, the response still returns HTTP 200 with error, findings, and any partial output; the error is also recorded in the app's activity feed.

Arguments:
  • input: Request body.
  • input.config: Stored Script config ID (cfg_...) whose current version is executed. Mutually exclusive with script. Required for server-side producers that must not supply raw source.
  • input.config_key: lookup_key of an app-level Script config whose current version is executed. Resolved among the app's configs that belong to no organization, never an organization's config with the same key. Mutually exclusive with script and config.
  • input.resolution_context_config: Optional Script config ID establishing the authorized installation context for imports.
  • input.run_as_agent: Agent ID (agt_...) to impersonate during execution. When set, the script's system.viewer is replaced with a viewer for this agent. Mutually exclusive with run_as_user. null by default.
  • input.run_as_user: User ID (usr_...) to impersonate during execution. When set, the script's system.viewer is replaced with a viewer for this user. Mutually exclusive with run_as_agent. null by default.
  • input.scope: Initial scope injected into the script execution context. Use this to supply variables, system, or other top-level scope keys.
  • input.script: The script source to execute. Defaults to an empty string. Mutually exclusive with config.
  • input.thread: Optional thread ID for agent execution. Requires run_as_agent, caller access to the thread, matching agent app and organization, and agent membership in the thread.
Returns:

The script execution result, including the return value, captured output, and any runtime error or diagnostic findings.

def runtime_env_vars(self) -> archastro.platform.types.common.RuntimeEnvVarList: 
293    def runtime_env_vars(self) -> RuntimeEnvVarList:
294        """
295        List runtime environment variables for scripts
296        Returns metadata for all runtime environment variables available to scripts
297        running within the specified app. The response lists each variable's name
298        and description but does not include resolved values.
299        Use this to surface the available `env.*` identifiers in script editor
300        autocompletion or to inspect which variables are configured for an app
301        before running a script.
302        Requires an authenticated viewer scoped to the specified app.
303
304        Returns:
305            Paginated list of runtime environment variable metadata for the app.
306        """
307        return self._http.request(
308            "/api/v1/scripts/runtime_env_vars",
309            response_type=RuntimeEnvVarList,
310        )

List runtime environment variables for scripts Returns metadata for all runtime environment variables available to scripts running within the specified app. The response lists each variable's name and description but does not include resolved values. Use this to surface the available env.* identifiers in script editor autocompletion or to inspect which variables are configured for an app before running a script. Requires an authenticated viewer scoped to the specified app.

Returns:

Paginated list of runtime environment variable metadata for the app.

def test( self, input: ScriptTestInput) -> archastro.platform.types.scripts.ScriptTestRunResult: 
312    def test(self, input: ScriptTestInput) -> ScriptTestRunResult:
313        """
314        Run a script test suite
315        Executes a Jest-style script test source (`describe` / `it` / `expect`) and
316        returns a structured assertion report. Use this endpoint to run unit tests
317        against script logic during development or in CI pipelines.
318        Imports of the form `import("script:<lookup_key>")` inside the test script
319        resolve against the `scripts` map supplied in the request body first, then
320        fall back to deployed scripts in the caller's app. This lets you test local
321        changes to scripts before deploying them.
322        Runtime environment variables defined for the app are automatically injected
323        into `variables.env` within the execution scope.
324        When a mid-run runtime error occurs (after some tests have already executed),
325        the endpoint returns HTTP 200 with `passed: false`, the partial per-test
326        breakdown, and a top-level `error` and `findings` describing the crash. When
327        the test source itself cannot be parsed, the endpoint returns HTTP 422 with
328        the syntax error message.
329
330        Args:
331            input: Request body.
332            input.resolution_context_config: Optional config ID establishing the authorized installation context for imports.
333            input.scope: Optional overrides for the execution scope. Accepts `variables`, `system`, or other top-level scope keys.
334            input.script: The test script source to execute. Should contain `describe` / `it` / `expect` blocks.
335            input.scripts: Optional map of local script sources keyed by lookup key (e.g. `"my_script"`). Used to resolve `import("script:<lookup_key>")` calls before falling back to deployed scripts in the caller's app.
336
337        Returns:
338            The assertion report for the test run, including per-suite and per-test results, assertion counts, captured output, and any runtime error or diagnostic findings.
339        """
340        return self._http.request(
341            "/api/v1/scripts/test",
342            method="POST",
343            body=input,
344            response_type=ScriptTestRunResult,
345        )

Run a script test suite Executes a Jest-style script test source (describe / it / expect) and returns a structured assertion report. Use this endpoint to run unit tests against script logic during development or in CI pipelines. Imports of the form import("script:<lookup_key>") inside the test script resolve against the scripts map supplied in the request body first, then fall back to deployed scripts in the caller's app. This lets you test local changes to scripts before deploying them. Runtime environment variables defined for the app are automatically injected into variables.env within the execution scope. When a mid-run runtime error occurs (after some tests have already executed), the endpoint returns HTTP 200 with passed: false, the partial per-test breakdown, and a top-level error and findings describing the crash. When the test source itself cannot be parsed, the endpoint returns HTTP 422 with the syntax error message.

Arguments:
  • input: Request body.
  • input.resolution_context_config: Optional config ID establishing the authorized installation context for imports.
  • input.scope: Optional overrides for the execution scope. Accepts variables, system, or other top-level scope keys.
  • input.script: The test script source to execute. Should contain describe / it / expect blocks.
  • input.scripts: Optional map of local script sources keyed by lookup key (e.g. "my_script"). Used to resolve import("script:<lookup_key>") calls before falling back to deployed scripts in the caller's app.
Returns:

The assertion report for the test run, including per-suite and per-test results, assertion counts, captured output, and any runtime error or diagnostic findings.

def validate( self, input: ScriptValidateInput) -> archastro.platform.types.expressions.ExpressionValidation: 
347    def validate(self, input: ScriptValidateInput) -> ExpressionValidation:
348        """
349        Validate a workflow script
350        Parses and statically analyzes the provided script source, returning a list
351        of diagnostic findings (errors and warnings) without executing the script.
352        Use this endpoint to power real-time syntax and type checking in script
353        editors.
354        The response always returns HTTP 200. Check the `findings` array in the
355        returned validation result for any errors or warnings. An empty `findings`
356        list means the script passed all static checks.
357        Requires an authenticated viewer. No additional app scope is needed.
358
359        Args:
360            input: Request body.
361            input.script: The script source to validate. Defaults to an empty string.
362
363        Returns:
364            Static analysis result containing a list of diagnostic findings for the script.
365        """
366        return self._http.request(
367            "/api/v1/scripts/validate",
368            method="POST",
369            body=input,
370            response_type=ExpressionValidation,
371        )

Validate a workflow script Parses and statically analyzes the provided script source, returning a list of diagnostic findings (errors and warnings) without executing the script. Use this endpoint to power real-time syntax and type checking in script editors. The response always returns HTTP 200. Check the findings array in the returned validation result for any errors or warnings. An empty findings list means the script passed all static checks. Requires an authenticated viewer. No additional app scope is needed.

Arguments:
  • input: Request body.
  • input.script: The script source to validate. Defaults to an empty string.
Returns:

Static analysis result containing a list of diagnostic findings for the script.