@elevasis/sdk 1.44.3 → 1.45.0

package/reference/sdk/framework/memory.mdx

@@ -1,326 +0,0 @@
----
-title: Memory System
-description: Cross-session project knowledge stored in .claude/memory/ -- deployment state, environment, decisions, and error patterns that persist between Claude Code sessions
-loadWhen: "Working with agent memory or session state"
----
-
-The memory system gives Claude Code a structured knowledge base for your project that survives across sessions. Deployment history, discovered credentials, architectural decisions, and error patterns are all written to `.claude/memory/` as the project evolves -- so the agent never starts from scratch.
-
-The `memory/` directory is gitignored and personal to each developer. The `profile/` subdirectory is created by `/meta init` during first-run setup. All other topics are created by the agent as the project evolves.
-
-## Purpose
-
-Without project memory, the agent starts every session with only the context of the current conversation. It cannot remember that you already deployed yesterday, that a particular credential is configured, or that you encountered and solved a specific TypeScript error last week.
-
-With project memory, the agent loads a root index at session start, sees what has been recorded, and can retrieve detail on demand. Error patterns are matched before diagnosis. Deployment state is available before deploying again. The agent can say "I've seen this before -- here's the fix" instead of repeating the same diagnostic process.
-
-## Architecture
-
-Memory is organized as a hierarchical index tree. Every directory has an `index.md` that maps to its children -- either content files or subdirectories with their own indexes.
-
-**The invariant:** A reader always starts at the root index and drills down. The agent reads `memory/index.md` at session start. It reads individual topic files on demand when the user asks about that topic or the agent is about to perform an action in that domain.
-
-**The scaling rule:** When a content file outgrows a single document, it graduates into a subdirectory:
-
-1. `topic.md` becomes `topic/index.md` + sub-files
-2. The parent index updates its link from `topic.md` to `topic/index.md`
-3. The new sub-index maps to the sub-files
-
-This pattern is recursive. Subdirectories can split further as needed. The agent applies its own judgment about when a file has grown past usefulness as a single document.
-
-### Starting Structure
-
-After `/meta init` and a first deployment, the structure looks like this:
-
-```
-.claude/memory/
-├── index.md                    # Root index -- read at session start
-├── profile/                    # Developer profile (created by /meta init)
-│   ├── index.md                # Profile summary with links to sub-files
-│   ├── identity.md             # Organization, industry, goals, integrations
-│   ├── skills.md               # Skill dimensions and Growth Log
-│   └── preferences.md          # Verbosity, guidance style, interaction patterns
-├── deployment-state.md         # Deploy IDs, resource inventory, org info
-├── environment.md              # Credentials, API keys, env vars
-├── decisions.md                # Architectural decisions and patterns
-└── errors/                     # Subdirectory -- multiple categories
-    ├── index.md                # Error category summary with counts
-    ├── deploy.md               # Deployment error patterns
-    ├── runtime.md              # Runtime execution error patterns
-    └── typescript.md           # Type and build error patterns
-```
-
-Profile tracking starts as a subdirectory because it has natural sub-topics from day one (identity, skills, preferences). Error tracking starts as a subdirectory because it naturally spans multiple categories. Other topics start as flat files.
-
-### Grown Structure
-
-As a project matures, other topics may split:
-
-```
-.claude/memory/
-├── index.md
-├── environment.md
-├── decisions.md
-├── deployment-state/           # Grew large enough to split
-│   ├── index.md
-│   ├── resources.md
-│   └── history.md
-└── errors/
-    ├── index.md
-    ├── deploy.md
-    ├── typescript.md
-    └── runtime/                # Runtime errors grew further
-        ├── index.md
-        ├── lead-scorer.md
-        └── email-sender.md
-```
-
-## Memory Topics
-
-### Developer Profile
-
-The `profile/` directory stores the developer's personal context -- organization details, skill levels, goals, and interaction preferences. It is created during `/meta init` guided setup and is the first thing the root index links to.
-
-```
-.claude/memory/profile/
-├── index.md          # Profile summary with links to sub-files
-├── identity.md       # Organization, industry, goals, integrations
-├── skills.md         # Skill dimensions and Growth Log
-└── preferences.md    # Verbosity, guidance style, interaction patterns
-```
-
-**`identity.md`** records the organization name, industry, size, project goals, and known tool integrations. Example:
-
-```markdown
-# Identity
-
-| Field | Value |
-| --- | --- |
-| Organization | Acme Corp |
-| Industry | E-commerce |
-| Size | 10-50 |
-
-## Project Goals
-
-- Automate lead scoring from Attio CRM
-- Send follow-up emails via Resend
-- Weekly pipeline reports
-
-## Known Integrations
-
-- Attio (CRM)
-- Resend (email)
-- Google Sheets (reporting)
-```
-
-**`skills.md`** stores four skill dimensions as structured values so the Adaptive Guidance rules in [Interaction Guidance](interaction-guidance.mdx) can apply them consistently. It also tracks a Growth Log so the agent can detect when a level upgrade is warranted. Example:
-
-```markdown
-# Skills
-
-| Dimension | Level | Since |
-| --- | --- | --- |
-| platformNavigation | oriented | 2026-02-25 |
-| apiIntegration | basic | 2026-02-25 |
-| automation | low-code | 2026-02-25 |
-| domainExpertise | high | 2026-02-25 |
-
-## Growth Log
-
-| Date | Observation | Dimension | Change |
-| --- | --- | --- | --- |
-| 2026-03-01 | Navigated to Execution Logs and filtered by resource without direction | platformNavigation | none -> oriented |
-```
-
-Valid levels per dimension:
-
-- `platformNavigation`: none / oriented / comfortable
-- `apiIntegration`: none / basic / proficient
-- `automation`: none / low-code / custom
-- `domainExpertise`: high / low
-
-**`preferences.md`** stores verbosity and proactive guidance settings. Example:
-
-```markdown
-# Preferences
-
-| Setting | Value |
-| --- | --- |
-| Verbosity | detailed |
-| Proactive guidance | yes |
-```
-
-### Root Index
-
-`memory/index.md` is the only file read at session start. It lists all topics with their last-updated dates, giving the agent enough context to know what has been recorded without loading any detail.
-
-```markdown
-# Project Memory
-
-Agent-maintained cross-session knowledge base. Updated automatically.
-
-| Entry | Topic | Last Updated |
-| --- | --- | --- |
-| [profile/](profile/index.md) | Developer profile (skills, identity, preferences) | 2026-02-25 |
-| [deployment-state.md](deployment-state.md) | Deploy history, resource inventory, org info | 2026-02-25 |
-| [environment.md](environment.md) | Credentials, API keys, env vars | 2026-02-25 |
-| [decisions.md](decisions.md) | Architectural decisions and patterns | 2026-02-26 |
-| [errors/](errors/index.md) | Error patterns by category | 2026-02-26 |
-```
-
-Subdirectory entries link to their `index.md` rather than the directory itself.
-
-### Deployment State
-
-`deployment-state.md` tracks the most recent deploy and resource inventory. The agent updates it after every successful deployment.
-
-```markdown
-# Deployment State
-
-## Latest Deploy
-
-| Field | Value |
-| --- | --- |
-| Date | 2026-02-26 |
-| Deploy ID | dep_abc123 |
-| Resource count | 2 |
-| Organization | acme-corp |
-
-## Resources
-
-- `echo` (workflow, dev) -- echoes input, starter resource
-- `lead-scorer` (workflow, prod) -- scores leads from Attio
-
-## Deploy History
-
-| Date | Deploy ID | Resources | Status |
-| --- | --- | --- | --- |
-| 2026-02-26 | dep_abc123 | 2 | success |
-| 2026-02-25 | dep_xyz789 | 1 | success |
-```
-
-### Environment
-
-`environment.md` records discovered credentials and environment variable status. The agent updates it when credentials are confirmed via the command center or deployment output.
-
-### Decisions
-
-`decisions.md` captures architectural choices as a table: which tools were chosen, what patterns were established, and why. The agent adds a row when the user makes a significant decision during development.
-
-## Error Tracking
-
-Error tracking is the first memory topic to outgrow a flat file. It starts as a subdirectory with one file per error category.
-
-### Error Index
-
-`errors/index.md` provides a high-level summary of known error patterns by category. The agent reads this file (via the root index) at session start.
-
-```markdown
-# Error Patterns
-
-Error pattern tracking by category. Updated when errors are diagnosed and resolved.
-
-| Entry | Category | Patterns | Total Occurrences | Last Seen |
-| --- | --- | --- | --- | --- |
-| [deploy.md](deploy.md) | Deployment | 2 | 3 | 2026-02-26 |
-| [runtime.md](runtime.md) | Runtime | 1 | 1 | 2026-02-26 |
-| [typescript.md](typescript.md) | TypeScript | 1 | 2 | 2026-02-25 |
-```
-
-- **Patterns** -- count of unique error patterns in the category file
-- **Total Occurrences** -- sum of all occurrences across patterns
-- **Last Seen** -- most recent date any error in this category was seen
-
-### Category Files
-
-Each category file is a table of known error patterns with resolutions:
-
-```markdown
-# Deploy Errors
-
-| Last Seen | Error | Resolution | Occurrences |
-| --- | --- | --- | --- |
-| 2026-02-25 | `ELEVASIS_PLATFORM_KEY not set` | Added key to `.env` | 2 |
-| 2026-02-26 | `Schema validation: missing outputSchema` | Added Zod output schema to workflow | 1 |
-```
-
-Runtime errors include the resource name since the same error in different resources may have different causes:
-
-```markdown
-# Runtime Errors
-
-| Last Seen | Resource | Error | Resolution | Occurrences |
-| --- | --- | --- | --- | --- |
-| 2026-02-26 | lead-scorer | `PlatformToolError: credential not found` | Set credential via `elevasis-sdk env set` | 1 |
-```
-
-### Error Resolution Flow
-
-When the agent encounters an error, it follows this sequence:
-
-1. Checks `memory/errors/index.md` (already loaded via root index) for a matching category
-2. If the relevant category has known patterns, reads the category file
-3. If a match exists, applies the known resolution immediately -- "I've seen this before, here's the fix"
-4. If no match exists, diagnoses normally, then logs the new pattern
-
-When the agent logs a resolved error:
-
-1. Reads the relevant category file (e.g., `memory/errors/deploy.md`)
-2. If the pattern already exists, increments `Occurrences` and updates `Last Seen`
-3. If it is a new pattern, adds a new row
-4. Updates the error index: recalculates `Patterns`, `Total Occurrences`, and `Last Seen`
-5. If the category file does not exist yet, creates it and adds a row to the error index
-
-## Scaling Rule
-
-When a file has grown past usefulness as a single document -- too many rows to scan, too many unrelated concerns, or too much context to load for a targeted lookup -- split it into a subdirectory.
-
-**Before split:**
-
-```
-memory/
-├── index.md
-└── deployment-state.md         # entry: deployment-state.md
-```
-
-**After split:**
-
-```
-memory/
-├── index.md                    # entry updated: deployment-state/ -> deployment-state/index.md
-└── deployment-state/
-    ├── index.md
-    ├── resources.md
-    └── history.md
-```
-
-The parent index link changes from `deployment-state.md` to `deployment-state/index.md`. The new sub-index maps to the sub-files. The agent applies this pattern at every depth level.
-
-## Maintenance
-
-### Pruning
-
-Keep content useful, not exhaustive:
-
-- Keep the most recent ~20 entries in tables that grow over time (deploy history, error patterns)
-- Drop patterns that have not recurred in 30 or more days unless the resolution was non-obvious
-- Summarize if patterns are worth preserving but detail is not
-
-### Index Hygiene
-
-- If a file exists but is not in its parent index, add it
-- If an index references a missing file, remove the row
-
-The agent self-heals on read. Index hygiene is applied as part of normal session operation.
-
-### Promotion
-
-If an error pattern recurs 3 or more times, promote it to a rule in the `CLAUDE.md` Rules section. Rules prevent errors rather than diagnosing them.
-
-## Relationship to Claude Code Auto-Memory
-
-Claude Code's auto-memory (`MEMORY.md`) and project memory (`.claude/memory/`) are complementary -- both should be active. Auto-memory captures organic discoveries; project memory captures structured project state that `CLAUDE.md` explicitly instructs the agent to record.
-
----
-
-**Last Updated:** 2026-02-25

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