@elevasis/sdk 1.44.2 → 1.45.0

package/reference/sdk/framework/resource-documentation.mdx

@@ -1,90 +0,0 @@
----
-title: Resource Documentation
-description: How docs ship alongside code in the Elevasis SDK -- directory structure, frontmatter schema, size limits, deploy behavior, and the /docs command
-loadWhen: "Working with resource documentation or the /docs command"
----
-
-`elevasis-sdk deploy` ships your code and your documentation atomically -- one command, no version drift. Documentation files live in a `docs/` directory at your project root and render in the Elevasis platform UI for operators using your resources.
-
-## Directory Structure
-
-Create `.mdx` files inside a `docs/` directory at your project root. Your Elevasis SDK project includes a starter structure:
-
-```
-my-project/
-├── docs/
-│   └── index.mdx          # Resource overview (included by default)
-├── src/
-│   └── index.ts            # Resource definitions
-└── elevasis.config.ts
-```
-
-A missing `docs/` directory is silently ignored -- documentation is optional. If the directory exists, its contents are included in the deploy payload alongside resource schemas.
-
-## Frontmatter Schema
-
-```yaml
----
-title: string       # Page title (required)
-description: string # Short description (optional)
-order: number       # Sort order within directory (optional, default: 0)
----
-```
-
-## Naming Conventions
-
-- `docs/index.md` is the root page and is always rendered first
-- Nested directories create sections: `docs/guides/getting-started.mdx`
-- File names become URL slugs: `setup-guide.mdx` renders at `/docs/setup-guide`
-- Arbitrary nesting is supported -- no depth limit
-
-## Size Limits
-
-- 100KB per file
-- 1MB total across all files in a deployment
-
-These limits are enforced by the CLI before the deploy request is sent. Validation errors include the file name and size.
-
-## Deploy Behavior
-
-When you run `elevasis-sdk deploy`:
-
-1. The CLI scans `docs/` recursively for `.mdx` files
-2. Each file's frontmatter (title, description, order) is parsed and stripped from the content
-3. Total size is validated against the 1MB limit and individual files against 100KB
-4. The documentation array is included in the deploy metadata alongside your resource schemas
-
-Documentation and code ship in the same transaction. There is no separate upload step and no way for documentation to drift out of sync with the deployed version.
-
-## The /docs Command
-
-The `/docs` command manages the permanent `docs/` tree in your project. It operates on everything in `docs/` except `docs/in-progress/` (owned by `/work`) and auto-generated files (`project-map.mdx`, `resource-map.mdx`).
-
-**Browse (default):** Running `/docs` with no arguments scans `docs/` recursively and presents a numbered list of user-maintained docs. Pick a number to read and discuss the doc, or say "create" or "verify."
-
-**Create:** `/docs create [description]` runs an interview-driven flow. It asks what you want to document, determines placement, scans `src/` to pre-populate from code, and creates the file with appropriate sections.
-
-Section templates by doc type:
-
-- **Resource guide:** Overview, Input/Output, How It Works, Platform Tools Used, Configuration
-- **Integration guide:** Overview, Setup (credentials), Data Model, Usage Patterns, Troubleshooting
-- **Architecture notes:** Context, Decision, Consequences, Alternatives Considered
-- **Process doc:** Purpose, Prerequisites, Steps, Recovery
-
-**Verify:** `/docs verify [file?]` checks docs against current code interactively. Without an argument, it scans all user-maintained docs, cross-references resource IDs, schema fields, and platform tools against `src/`, and offers to fix or create docs for undocumented resources.
-
-## Command Routing Reference
-
-| Scenario                                | Command                                               |
-| --------------------------------------- | ----------------------------------------------------- |
-| Starting new work                       | `/work` (auto-detects new work from your description) |
-| Resuming yesterday's work               | `/work` (auto-resumes if one task is in-progress)     |
-| Browsing what docs exist                | `/docs`                                               |
-| Creating a reference doc (not a task)   | `/docs create`                                        |
-| Checking if docs match current code     | `/docs verify`                                        |
-| Full maintenance pipeline (8 steps)     | `/meta fix`                                           |
-| Deploying code and auto-generating maps | `/meta deploy`                                        |
-
----
-
-**Last Updated:** 2026-03-06

package/reference/sdk/roadmap.mdx

@@ -1,164 +0,0 @@
----
-title: Roadmap
-description: Planned SDK features -- error taxonomy, retry semantics, circuit breaker, metrics, alerting, and resource lifecycle extensions
----
-
-**Status:** Mixed -- some features below are implemented, others remain planned. Each section notes its current status.
-
-For currently implemented behavior, see [Runtime](runtime.mdx).
-
----
-
-## Structured Error Taxonomy
-
-**Status: Partially implemented.** The runtime has a structured error hierarchy (`ExecutionError`, `PlatformToolError`, `ToolingError`) with error codes and context fields. The taxonomy below describes a planned _redesign_ that is not yet implemented.
-
-The current runtime reports errors as plain strings. A future SDK version will introduce a structured error taxonomy. All SDK errors will extend `ResourceError`, the base class for errors surfaced through the execution protocol.
-
-Every error carries: `message` (string), `code` (string enum), `details` (optional structured data), and `retryable` (boolean).
-
-**Error types:**
-
-- **`ResourceError`** -- Base class for all SDK errors
-- **`ValidationError`** -- Input or output schema validation failed. Thrown automatically when Zod `.parse()` fails. Code: `VALIDATION_ERROR`. Not retryable.
-- **`StepError`** -- A workflow step handler threw. Includes `stepId` and `stepName`. Code: `STEP_ERROR`. Retryable (transient failures may succeed on retry).
-- **`ToolError`** -- A tool execution failed. Includes `toolName`. Code: `TOOL_ERROR`. Retryability depends on the underlying error.
-- **`TimeoutError`** -- Execution exceeded the deadline. Code: `TIMEOUT`. Retryable.
-- **`CancellationError`** -- Execution was cancelled by the platform or user. Code: `CANCELLED`. Not retryable.
-
----
-
-## Retry Semantics
-
-**Status: Planned.**
-
-Retries are platform-side only -- workers are ephemeral and never retry internally.
-
-- **Configuration:** Per-resource via `maxRetries` (default: 0) and `backoffStrategy` (exponential with jitter)
-- **Retryable conditions:** Worker crash or timeout (worker terminated by `AbortSignal`)
-- **Non-retryable conditions:** Worker reports `status: 'failed'` (handler ran and returned an error -- application logic, not infrastructure failure), user cancellation
-- **Idempotency:** On retry, the same `executionId` is reused. Design handlers to be idempotent where possible.
-
----
-
-## Workflow Step Failure
-
-**Status: Planned.** The current runtime uses fail-fast behavior: when a step handler throws, the worker logs a `step-failed` context entry and re-throws the original error unchanged. The `onError` callback, `completedSteps`, and `partialOutput` features described below are not yet implemented.
-
-Default behavior is fail-fast: when a step throws, the workflow fails immediately.
-
-- **Error handler:** Optional `onError` callback per step. The callback receives the error and can return a recovery value or rethrow to propagate the failure.
-- **Partial output:** Steps completed before the failure are included in the error response. The platform receives: `failedStepId`, `completedSteps[]` (IDs of successfully completed steps), and `partialOutput` (the last successful step's output).
-
-**Proposed step error response format** (not yet implemented -- subject to change):
-
-```json
-{
-  "status": "failed",
-  "error": {
-    "code": "STEP_ERROR",
-    "message": "Email delivery failed: invalid address",
-    "stepId": "send-welcome",
-    "stepName": "Send Welcome Email"
-  },
-  "completedSteps": ["validate"],
-  "partialOutput": { "clientName": "Jane", "isValid": true }
-}
-```
-
----
-
-## Agent Failure Modes
-
-**Status: Planned.** Agent execution runs in ephemeral worker threads with full tool calling support via `PostMessageLLMAdapter`. The current runtime uses fail-fast behavior for all agent error paths; the richer failure handling described below is not yet implemented.
-
-**Current behavior:** Any unhandled error from the agent (including `AgentMaxIterationsError` thrown by `@repo/core` when the iteration limit is reached) propagates out of the worker and is reported as a failed execution. The worker sends: `{ type: 'result', status: 'failed', error: 'ErrorName: message', logs, metrics: { durationMs } }`. There is no graceful termination, partial output, or retry logic in the worker itself.
-
-**Planned improvements:**
-
-- **Max iterations reached:** Instead of throwing, the agent returns the best output produced so far, plus a warning flag (`maxIterationsReached: true`). This becomes a graceful termination rather than a failure.
-- **Tool crash:** Tool errors are caught by the SDK runtime, formatted as a tool result, and sent back to the LLM. The LLM decides whether to retry, try a different approach, or give up.
-- **Model refusal:** If the model refuses the prompt, the SDK retries once with an adjusted system prompt. If the retry also refuses, the agent fails with `code: 'MODEL_REFUSAL'`.
-- **Model API error:** Network errors, rate limits, or server errors from the model provider. The SDK retries with exponential backoff (3 attempts, 1s/2s/4s), then fails with `code: 'MODEL_ERROR'`.
-- **Agent error response includes:** `iterationCount` (LLM iterations completed), `toolCallHistory` (array of tool calls made), `lastModelResponse` (final response from the LLM before failure).
-
----
-
-## Circuit Breaker
-
-**Status: Planned.**
-
-The platform will implement a circuit breaker to prevent runaway failures:
-
-- **Trip condition:** 5 consecutive failures on the same resource within a 10-minute window
-- **Action:** Pause executions for 60 seconds. New execution requests for that resource return `503` with: "Resource temporarily unavailable (circuit breaker tripped)"
-- **Auto-recovery:** After the 60-second pause, the next execution attempt is allowed through. If it succeeds, the circuit breaker resets. If it fails, the pause extends (120s, then 240s, capped at 5 minutes).
-- **Alerting:** You are notified via webhook callback or email when the circuit breaker trips. Configurable per organization.
-
----
-
-## Metrics
-
-**Status: Planned.**
-
-### Auto-Collected
-
-The SDK runtime and platform will automatically collect these metrics for every execution:
-
-- `execution_duration_ms` -- Total wall-clock time from request received to result sent
-- `step_duration_ms` -- Per-step timing for workflows (array of `{ stepId, durationMs }`)
-- `iteration_count` -- Number of LLM loop iterations for agents
-- `ai_token_usage` -- Token counts per model call: `{ prompt_tokens, completion_tokens, total_tokens }`
-- `ai_cost_usd` -- Calculated from model pricing multiplied by token usage
-- `tool_call_count` -- Total number of tool invocations during the execution
-- `tool_call_duration_ms` -- Per-tool timing (array of `{ toolName, durationMs }`)
-- `error_count` -- Number of errors encountered (including recovered errors)
-
-### Cost Attribution
-
-Metrics are aggregated at multiple levels:
-
-- **Per-execution:** Total AI spend and total duration
-- **Per-resource:** Aggregated over configurable time periods (daily, weekly, monthly)
-- **Per-organization:** Total platform cost (execution time + AI spend + managed hosting compute)
-- **Visibility:** Platform dashboard and the CLI via `elevasis-sdk executions <resourceId>`
-
-### Developer-Defined Metrics
-
-A future SDK version will support custom metrics emitted from your handlers:
-
-- `sdk.metrics.counter('custom_name', value)` -- Increment a counter
-- `sdk.metrics.gauge('queue_depth', value)` -- Set a point-in-time gauge value
-- Custom metrics are stored alongside auto-collected metrics and queryable through the same APIs
-
----
-
-## Alerting
-
-**Status: Planned.**
-
-Developer-configurable alerts for production monitoring:
-
-- **Error rate threshold:** Notify when more than X% of executions fail within Y minutes
-- **Latency percentile:** Notify when p95 execution duration exceeds a threshold
-- **Cost budget:** Notify when daily or weekly AI spend exceeds a configured limit
-- **Channel:** Webhook callback to a developer-provided URL (integrates with Slack, PagerDuty, and similar services via webhook)
-
----
-
-## Resource Lifecycle Extensions
-
-**Status: Planned.**
-
-### Deprecation Status
-
-Beyond the current `dev` and `prod` statuses, two additional statuses are planned:
-
-- **`deprecated`** -- Marked via the platform UI. Existing executions continue working. New executions show a warning: "This resource is deprecated." The resource still appears in the platform and can still be triggered.
-- **`offline`** -- Set automatically when a deployment is unregistered (for example, after a failed deploy or explicit deletion). Clears automatically on the next successful deploy. No executions are accepted while a resource is offline.
-
-Deprecation requires no automatic removal -- the developer must explicitly delete the resource to remove it.
-
----
-
-**Last Updated:** 2026-03-08