@elevasis/sdk 0.5.12 → 0.5.14

package/reference/{runtime/index.mdx → runtime.mdx}

@@ -1,141 +1,173 @@
----
-title: Execution Runtime
-description: How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, and observability
-loadWhen: "Debugging execution behavior or understanding the runtime model"
----
-
-This page covers everything that happens after you deploy -- how resources execute as managed processes, how failures surface to you, and what observability data you can access. For resource limits and quotas, see [Resource Limits & Quotas](limits.mdx).
-
----
-
-## Execution Lifecycle
-
-### The Four Stages
-
-Every execution traverses four stages: trigger, route, execute, and return.
-
-1. **Trigger** -- A user, CLI command, or API call initiates execution. The platform creates an execution record with `status: 'running'` and generates a unique `executionId`.
-2. **Route** -- The platform resolves the target resource from the registry. All resources (static and external) coexist in a single in-memory registry with no database queries at lookup time.
-3. **Execute** -- An ephemeral worker thread is created from your deployed bundle and sent the execution request. The worker matches the `resourceId` to your definition, validates the input against your Zod schema, and runs the handler. For workflows, steps execute sequentially following the `next` chain. The worker is terminated immediately after execution completes.
-4. **Return** -- The worker posts the result back to the platform. The platform stores the final result, updates the execution record, and fans events out to AI Studio and CLI subscribers.
-
-### Concurrency Model
-
-Workers are ephemeral -- each execution creates a new worker thread. There is no persistent pool:
-
-- **Per-execution isolation:** Each execution gets its own worker thread. Concurrent executions for the same organization run in separate workers with no shared state.
-- **Memory:** Each worker is capped at 256MB. Concurrent workers multiply memory usage proportionally.
-- **No cold start:** Workers are created fresh per execution. Your first execution and hundredth are identical in terms of startup behavior.
-
-### Timeout Enforcement
-
-Timeouts are enforced by the platform. You do not handle them explicitly in your code:
-
-- **Default timeout:** A platform default applies to all resource types unless overridden.
-- **Per-resource override:** Agents can configure `constraints.timeout` in the agent definition. Workflows use the platform default.
-- **Enforcement:** When a timeout fires, the worker is terminated immediately -- even if it is stuck in a synchronous loop. No special handler signature is required on your part.
-
-### Cancellation Protocol
-
-Cancellation is initiated by the platform and requires no special code in your handler:
-
-1. A cancellation request is received -- via CLI, API, or platform timeout.
-2. The platform aborts the execution controller registered for that `executionId`.
-3. The worker is terminated immediately (kills the worker even if stuck in a synchronous loop).
-4. The platform records the cancellation in the execution record.
-
-**What triggers cancellation:**
-
-- You call `POST /api/external/executions/:resourceId/:executionId/cancel` via CLI or API
-- The platform timeout expires
-- The resource is deleted while an execution is in-flight
-
----
-
-## Error Handling
-
-### How Errors Reach You
-
-Errors are displayed depending on the surface you use to inspect them:
-
-- **AI Studio:** Shows the error message and execution status. Example: `Remote resource 'onboard-client' failed: Email delivery failed: invalid address`
-- **CLI (`elevasis-sdk execution <resourceId> <id>`):** Shows full execution detail including the error message. The `--json` flag includes an `error` field in structured output.
-- **Error message source:** The error string comes directly from your handler's catch block (`String(err)`). The platform stores this verbatim and displays it as-is. Write descriptive error messages in your handlers -- they surface directly to users.
-
-### What Causes a Failed Execution
-
-- **Unhandled exception in your handler:** The worker reports `status: 'failed'` with the error message.
-- **Memory limit exceeded (256MB):** The worker crashes with an out-of-memory error. The platform catches this; other tenants are unaffected.
-- **Timeout exceeded:** The platform terminates the worker and marks the execution failed with a timeout reason.
-- **Cancellation:** Execution is marked cancelled.
-
----
-
-## Observability
-
-### Logging
-
-You produce logs using standard `console` methods -- no special logger object is needed:
-
-- **Console interception:** The SDK worker runtime intercepts `console.log`, `console.warn`, and `console.error` during handler execution and captures them as structured `{ level, message }` entries.
-- **Level mapping:** `console.log` maps to `info`, `console.warn` maps to `warn`, `console.error` maps to `error`.
-- **No changes required:** Any code that already uses `console.log` automatically has its output captured. Existing code works without modification.
-
-### Log Transport
-
-Logs are delivered to the platform atomically with the execution result:
-
-- **Bundled delivery:** All logs for an execution are included in the result message when the handler completes. There is no real-time streaming -- logs arrive with the final result.
-- **Crash behavior:** If the worker crashes before completing, logs captured up to the crash point are lost. The platform records only the crash error.
-
-### Log Retention and Display
-
-- **Retention:** 30 days by default (configurable per plan).
-- **Real-time fanout:** After execution completes, logs are stored and fanned out to AI Studio and CLI subscribers. AI Studio shows them in the execution detail view.
-- **CLI access:** Use `elevasis-sdk execution <resourceId> <id>` to view execution details including logs.
-
----
-
-## Resource Lifecycle
-
-### Status
-
-Every resource on the platform has a status that you control in your definition:
-
-- **`dev`** -- Default for new resources. Visible in AI Studio and executable, but marked with a "Development" badge. Use this during testing and iteration.
-- **`prod`** -- Set `status: 'prod'` in your resource definition before deploying. No badge. This is the live, production-ready state.
-
-### Versioning
-
-v1 versioning is intentionally simple:
-
-- **One active version per resource per org.** Deploying replaces the running version. There is no version history at the resource level; previous deploys are marked stopped.
-- **Immutable per deploy.** A resource definition is frozen at deploy time. Changing code requires a new deploy.
-
-### Deletion
-
-- **Via CLI:** Remove the resource from your `OrganizationResources` export and run `elevasis-sdk deploy`. Resources absent from the new bundle are automatically deregistered from the platform.
-- **Via AI Studio:** The delete button unregisters the resource immediately and marks the deployment stopped.
-- **In-flight executions:** Workers already running complete normally. Deletion affects only new execution attempts.
-- **Data retention:** Execution logs and history for a deleted resource are retained for 30 days, then purged.
-
----
-
-## Platform Storage
-
-Your deployed bundle is stored in Supabase Storage. On API restart, the platform re-registers all active deployments from the database and re-downloads bundles if needed. This means:
-
-- **No data loss on restart:** Your resources are automatically re-registered after platform restarts.
-- **No action required from you:** The platform handles recovery transparently.
-
----
-
-## Platform Maintenance
-
-- **Rolling updates:** Platform upgrades trigger a re-registration of all active deployments on startup. No in-flight executions are lost (workers are ephemeral and complete independently).
-- **In-flight executions during restart:** Already-running workers complete normally. New executions use the newly reloaded registry after restart.
-- **Advance notice:** You will receive 24-hour advance notice for breaking maintenance windows. These are rare and reserved for major infrastructure changes.
-
----
-
-**Last Updated:** 2026-02-25
+---
+title: Execution Runtime
+description: How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, observability, resource limits, and v1 limitations
+loadWhen: "Debugging execution behavior or understanding the runtime model"
+---
+
+This page covers everything that happens after you deploy -- how resources execute as managed processes, how failures surface to you, what observability data you can access, and the hard limits enforced on all executions.
+
+---
+
+## Execution Lifecycle
+
+### The Four Stages
+
+Every execution traverses four stages: trigger, route, execute, and return.
+
+1. **Trigger** -- A user, CLI command, or API call initiates execution. The platform creates an execution record with `status: 'running'` and generates a unique `executionId`.
+2. **Route** -- The platform resolves the target resource from the registry. All resources (static and external) coexist in a single in-memory registry with no database queries at lookup time.
+3. **Execute** -- An ephemeral worker thread is created from your deployed bundle and sent the execution request. The worker matches the `resourceId` to your definition, validates the input against your Zod schema, and runs the handler. For workflows, steps execute sequentially following the `next` chain. The worker is terminated immediately after execution completes.
+4. **Return** -- The worker posts the result back to the platform. The platform stores the final result, updates the execution record, and fans events out to AI Studio and CLI subscribers.
+
+### Concurrency Model
+
+Workers are ephemeral -- each execution creates a new worker thread. There is no persistent pool:
+
+- **Per-execution isolation:** Each execution gets its own worker thread. Concurrent executions for the same organization run in separate workers with no shared state.
+- **Memory:** Each worker is capped at 256MB. Concurrent workers multiply memory usage proportionally.
+- **No cold start:** Workers are created fresh per execution. Your first execution and hundredth are identical in terms of startup behavior.
+
+### Timeout Enforcement
+
+Timeouts are enforced by the platform. You do not handle them explicitly in your code:
+
+- **Default timeout:** A platform default applies to all resource types unless overridden.
+- **Per-resource override:** Agents can configure `constraints.timeout` in the agent definition. Workflows use the platform default.
+- **Enforcement:** When a timeout fires, the worker is terminated immediately -- even if it is stuck in a synchronous loop. No special handler signature is required on your part.
+
+### Cancellation
+
+Cancellation is initiated by the platform and requires no special code in your handler. The worker is terminated immediately and the execution is recorded as cancelled.
+
+**What triggers cancellation:**
+
+- You call `POST /api/external/executions/:resourceId/:executionId/cancel` via CLI or API
+- The platform timeout expires
+- The resource is deleted while an execution is in-flight
+
+---
+
+## Error Handling
+
+### How Errors Reach You
+
+Errors are displayed depending on the surface you use to inspect them:
+
+- **AI Studio:** Shows the error message and execution status. Example: `Remote resource 'onboard-client' failed: Email delivery failed: invalid address`
+- **CLI (`elevasis-sdk execution <resourceId> <id>`):** Shows full execution detail including the error message. The `--json` flag includes an `error` field in structured output.
+- **Error message source:** The error string comes directly from your handler's catch block (`String(err)`). The platform stores this verbatim and displays it as-is. Write descriptive error messages in your handlers -- they surface directly to users.
+
+### What Causes a Failed Execution
+
+- **Unhandled exception in your handler:** The worker reports `status: 'failed'` with the error message.
+- **Memory limit exceeded (256MB):** The worker crashes with an out-of-memory error. The platform catches this; other tenants are unaffected.
+- **Timeout exceeded:** The platform terminates the worker and marks the execution failed with a timeout reason.
+- **Cancellation:** Execution is marked cancelled.
+
+---
+
+## Observability
+
+### Logging
+
+You produce logs using standard `console` methods -- no special logger object is needed:
+
+- **Console interception:** The SDK worker runtime intercepts `console.log`, `console.warn`, and `console.error` during handler execution and captures them as structured `{ level, message }` entries.
+- **Level mapping:** `console.log` maps to `info`, `console.warn` maps to `warn`, `console.error` maps to `error`.
+- **No changes required:** Any code that already uses `console.log` automatically has its output captured. Existing code works without modification.
+
+### Log Transport
+
+Logs are delivered to the platform atomically with the execution result:
+
+- **Bundled delivery:** All logs for an execution are included in the result message when the handler completes. There is no real-time streaming -- logs arrive with the final result.
+- **Crash behavior:** If the worker crashes before completing, logs captured up to the crash point are lost. The platform records only the crash error.
+
+### Log Retention and Display
+
+- **Retention:** 30 days by default (configurable per plan).
+- **Real-time fanout:** After execution completes, logs are stored and fanned out to AI Studio and CLI subscribers. AI Studio shows them in the execution detail view.
+- **CLI access:** Use `elevasis-sdk execution <resourceId> <id>` to view execution details including logs.
+
+---
+
+## Resource Lifecycle
+
+### Status
+
+Every resource on the platform has a status that you control in your definition:
+
+- **`dev`** -- Default for new resources. Visible in AI Studio and executable, but marked with a "Development" badge. Use this during testing and iteration.
+- **`prod`** -- Set `status: 'prod'` in your resource definition before deploying. No badge. This is the live, production-ready state.
+
+### Versioning
+
+v1 versioning is intentionally simple:
+
+- **One active version per resource per org.** Deploying replaces the running version. There is no version history at the resource level; previous deploys are marked stopped.
+- **Immutable per deploy.** A resource definition is frozen at deploy time. Changing code requires a new deploy.
+
+### Deletion
+
+- **Via CLI:** Remove the resource from your `OrganizationResources` export and run `elevasis-sdk deploy`. Resources absent from the new bundle are automatically deregistered from the platform.
+- **Via AI Studio:** The delete button unregisters the resource immediately and marks the deployment stopped.
+- **In-flight executions:** Workers already running complete normally. Deletion affects only new execution attempts.
+- **Data retention:** Execution logs and history for a deleted resource are retained for 30 days, then purged.
+
+---
+
+## Resource Limits & Quotas
+
+### Per-Worker Limits
+
+Limits enforced per worker thread at runtime:
+
+| Resource         | Value                                                       |
+| ---------------- | ----------------------------------------------------------- |
+| Memory (V8 heap) | 256MB per worker                                            |
+| Disk             | Bundle file only (ephemeral, not persistent across deploys) |
+
+- **Memory:** Enforced by the platform. Exceeding 256MB crashes the worker. The platform catches the error; other tenants are unaffected. If your workflow processes large datasets, consider streaming or batching to stay within the limit.
+- **Disk:** Your bundle is written to disk during deploy and available to the worker at execution time. It is not a persistent write surface -- do not write files to disk from within your handler expecting them to persist.
+
+### Scale Limits
+
+Hard limits to prevent abuse and ensure platform stability:
+
+| Limit                              | Value         |
+| ---------------------------------- | ------------- |
+| Max execution duration (workflows) | 300s (5 min)  |
+| Max execution duration (agents)    | 600s (10 min) |
+| Max log volume                     | 100MB/day     |
+| Max deploy frequency               | 60/day        |
+
+- **Execution duration:** Executions exceeding the timeout are terminated by the platform. The execution is marked failed with a timeout reason.
+- **Log volume:** Total log output across all executions is capped at 100MB per day. Logs beyond this threshold may be truncated.
+- **Deploy frequency:** 60 deploys per day is generous for normal development. This limit prevents accidental deploy loops (for example, a CI pipeline misconfigured to deploy on every commit).
+
+### Networking
+
+- **Outbound:** Unrestricted. Your handlers can call any external API (OpenAI, Twilio, Stripe, etc.) from within the worker.
+- **Inbound:** Workers receive input from the platform coordinator via internal message passing -- they are not exposed to the network directly.
+- **No ports:** Workers communicate with the platform via zero-network-overhead message passing. No port allocation occurs.
+- **Isolation:** Workers have no access to other organizations' data or platform credentials by default. Supabase credentials are not present in the worker environment.
+
+---
+
+## v1 Limitations
+
+| Limitation                                      | Reason                                                                                                                                                                                           | Future path                                                                                                             |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| **No nested execution from external resources** | External resources cannot call back to the platform's execution coordinator to trigger other resources as sub-executions.                                                                        | A callback API endpoint that external processes can call to trigger nested executions (requires auth token forwarding). |
+| **No streaming logs**                           | Execution logs are returned in the response body after completion. There is no real-time SSE streaming from within the worker.                                                                   | SSE/WebSocket push from external processes to the platform log system.                                                  |
+| **Static resource priority conflicts**          | If your organization has a static (monorepo) resource with the same ID as a resource in your SDK bundle, the deploy will fail. Static definitions always take priority and cannot be overridden. | Conflict detection is surfaced in the CLI with a clear error message.                                                   |
+
+---
+
+## Organization Provisioning
+
+Organization creation is currently admin-only. If you need a new organization provisioned for SDK access, contact the Elevasis team. Self-serve organization creation and API key generation is on the roadmap.
+
+---
+
+**Last Updated:** 2026-03-06