@elevasis/sdk 0.5.12 → 0.5.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/cli.cjs +144 -118
  2. package/dist/index.d.ts +19 -253
  3. package/dist/index.js +20 -9
  4. package/dist/templates.js +62 -59
  5. package/dist/types/worker/adapters/index.d.ts +0 -1
  6. package/dist/worker/index.js +47 -53
  7. package/package.json +1 -1
  8. package/reference/_navigation.md +13 -57
  9. package/reference/{cli/index.mdx → cli.mdx} +568 -505
  10. package/reference/concepts.mdx +164 -0
  11. package/reference/deployment/api.mdx +297 -297
  12. package/reference/deployment/command-center.mdx +226 -0
  13. package/reference/deployment/index.mdx +158 -153
  14. package/reference/framework/agent.mdx +156 -151
  15. package/reference/framework/index.mdx +182 -103
  16. package/reference/{developer → framework}/interaction-guidance.mdx +182 -182
  17. package/reference/framework/memory.mdx +326 -347
  18. package/reference/framework/project-structure.mdx +277 -298
  19. package/reference/framework/tutorial-system.mdx +222 -0
  20. package/reference/{getting-started/index.mdx → getting-started.mdx} +152 -148
  21. package/reference/index.mdx +131 -114
  22. package/reference/platform-tools/adapters.mdx +868 -929
  23. package/reference/platform-tools/index.mdx +354 -195
  24. package/reference/resources/index.mdx +339 -336
  25. package/reference/resources/patterns.mdx +355 -354
  26. package/reference/resources/types.mdx +207 -207
  27. package/reference/{roadmap/index.mdx → roadmap.mdx} +163 -147
  28. package/reference/{runtime/index.mdx → runtime.mdx} +173 -141
  29. package/reference/{troubleshooting/common-errors.mdx → troubleshooting.mdx} +223 -210
  30. package/dist/types/worker/adapters/trello.d.ts +0 -14
  31. package/reference/concepts/index.mdx +0 -203
  32. package/reference/deployment/command-center-ui.mdx +0 -151
  33. package/reference/deployment/command-view.mdx +0 -154
  34. package/reference/framework/documentation.mdx +0 -92
  35. package/reference/platform-tools/examples.mdx +0 -170
  36. package/reference/runtime/limits.mdx +0 -75
  37. package/reference/security/credentials.mdx +0 -141
package/dist/templates.js CHANGED
@@ -31,26 +31,30 @@ ui/dist/
31
31
 
32
32
  // src/cli/commands/templates/core/claude.ts
33
33
  function claudeSettingsTemplate() {
34
- return JSON.stringify({
35
- autoCompact: false,
36
- statusLine: {
37
- type: "command",
38
- command: "node .claude/scripts/statusline-command.js"
34
+ return JSON.stringify(
35
+ {
36
+ autoCompact: false,
37
+ statusLine: {
38
+ type: "command",
39
+ command: "node .claude/scripts/statusline-command.js"
40
+ },
41
+ hooks: {
42
+ PreToolUse: [
43
+ {
44
+ matcher: "Write|Edit|MultiEdit|Bash",
45
+ hooks: [
46
+ {
47
+ type: "command",
48
+ command: "node .claude/hooks/enforce-sdk-boundary.mjs"
49
+ }
50
+ ]
51
+ }
52
+ ]
53
+ }
39
54
  },
40
- hooks: {
41
- PreToolUse: [
42
- {
43
- matcher: "Write|Edit|MultiEdit|Bash",
44
- hooks: [
45
- {
46
- type: "command",
47
- command: "node .claude/hooks/enforce-sdk-boundary.mjs"
48
- }
49
- ]
50
- }
51
- ]
52
- }
53
- }, null, 2) + "\n";
55
+ null,
56
+ 2
57
+ ) + "\n";
54
58
  }
55
59
  function claudeStatuslineScriptTemplate() {
56
60
  return `#!/usr/bin/env node
@@ -253,16 +257,16 @@ proactivity -- to their assessed levels.
253
257
 
254
258
  | Resource | Location | When to Load |
255
259
  | --- | --- | --- |
256
- | Workspace concepts | \`reference/concepts/index.mdx\` | User asks "what is...?" or needs conceptual grounding |
260
+ | Workspace concepts | \`reference/concepts.mdx\` | User asks "what is...?" or needs conceptual grounding |
257
261
  | SDK patterns and examples | \`reference/resources/patterns.mdx\` | Building or modifying a workflow |
258
262
  | Platform tool catalog | \`reference/platform-tools/index.mdx\` | Connecting to external services |
259
- | CLI reference | \`reference/cli/index.mdx\` | Running execution/platform operations |
260
- | Credential model | \`reference/security/credentials.mdx\` | Setting up integrations or tool access |
261
- | Interaction guidance | \`reference/developer/interaction-guidance.mdx\` | Unsure how to adapt for a skill combination |
263
+ | CLI reference | \`reference/cli.mdx\` | Running execution/platform operations |
264
+ | Credential model | \`reference/platform-tools/index.mdx\` | Setting up integrations or credential security |
265
+ | Interaction guidance | \`reference/framework/interaction-guidance.mdx\` | Unsure how to adapt for a skill combination |
262
266
  | Error history | \`.claude/memory/errors/index.md\` | Debugging errors, checking past fixes |
263
- | Command View model | \`reference/deployment/command-view.mdx\` | Deploying or building resources that invoke other resources |
264
- | Command Center UI reference | \`reference/deployment/command-center-ui.mdx\` | User asks about post-deployment UI or Command Center navigation |
265
- | SDK error reference | \`reference/troubleshooting/common-errors.mdx\` | Unknown error not in workspace memory |
267
+ | Command View model | \`reference/deployment/command-center.mdx\` | Deploying or building resources that invoke other resources |
268
+ | Command Center UI reference | \`reference/deployment/command-center.mdx\` | User asks about post-deployment UI or Command Center navigation |
269
+ | SDK error reference | \`reference/troubleshooting.mdx\` | Unknown error not in workspace memory |
266
270
  | Project map | \`docs/project-map.mdx\` | Session start, project orientation |
267
271
  | Resource inventory | \`docs/resource-map.mdx\` | Finding a specific resource by name or ID |
268
272
  | Project priorities | \`docs/priorities.mdx\` | Deciding what to work on next |
@@ -288,7 +292,7 @@ Use \`pnpm exec elevasis-sdk\` for runtime commands (resolves the locally instal
288
292
  - \`pnpm exec elevasis-sdk execution <resource-id> <execution-id>\` -- inspect execution detail
289
293
 
290
294
  Organization is derived from your API key -- no org prefix needed in the resource ID.
291
- For full CLI reference: \`reference/cli/index.mdx\`
295
+ For full CLI reference: \`reference/cli.mdx\`
292
296
 
293
297
  ## Rules
294
298
 
@@ -303,8 +307,8 @@ SDK patterns (imports, source structure, platform tools) are auto-loaded from
303
307
 
304
308
  When an error occurs:
305
309
  1. Check \`.claude/memory/errors/\` first for past fixes
306
- 2. If new, check \`reference/troubleshooting/common-errors.mdx\`
307
- 3. After resolving, record in \`memory/errors/\` with context and fix
310
+ 2. If new, check \`reference/troubleshooting.mdx\`
311
+ 3. After resolving, record in \`.claude/memory/errors/\` with context and fix
308
312
  4. If an error recurs 3+ times, add a rule to \`.claude/rules/workspace-patterns.md\`${ctx.hasUI ? `
309
313
 
310
314
  ### UI App (\`ui/\`)
@@ -313,7 +317,8 @@ When an error occurs:
313
317
  - Import from \`@elevasis/sdk-ui\`, never from \`@elevasis/sdk\` or \`@repo/ui\`
314
318
  - Dev server runs on port 5100: \`cd ui && pnpm dev\`
315
319
  - Set \`VITE_WORKOS_CLIENT_ID\` in \`ui/.env\` before running
316
- - \`ElevasisProvider\` is pre-configured in \`ui/src/App.tsx\` (oauth mode, redirectUri \`http://localhost:5100/auth-redirect\`, apiUrl \`http://localhost:5170\`)
320
+ - \`ElevasisCoreProvider\` (headless, no Mantine dependency) is pre-configured in \`ui/src/App.tsx\` with \`auth={{ mode: 'oauth', clientId, redirectUri }}\`, \`apiUrl="http://localhost:5170"\`, and \`theme={{ colorScheme: 'dark', preset: 'default' }}\`
321
+ - To use pre-built Mantine components from \`@elevasis/sdk-ui\`, switch to \`ElevasisUIProvider\` and install \`@mantine/core\` and \`@mantine/hooks\`
317
322
  - OAuth redirect is handled by the \`AuthRedirect\` component at \`/auth-redirect\` -- it uses \`useAuthContext()\` from \`@elevasis/sdk-ui/auth\` and navigates home once \`user\` is set
318
323
  - API must be running on port 5170 for the UI to work (\`pnpm --filter api dev\` from the platform monorepo)` : ""}
319
324
 
@@ -335,7 +340,7 @@ based on what you find.
335
340
  - When growth is observed, note it in the skills.md Growth Log.
336
341
 
337
342
  For detailed per-dimension adaptation rules, read
338
- \`reference/developer/interaction-guidance.mdx\`.
343
+ \`reference/framework/interaction-guidance.mdx\`.
339
344
 
340
345
  ## Commands
341
346
 
@@ -344,7 +349,7 @@ For detailed per-dimension adaptation rules, read
344
349
  | \`/meta\` | Project lifecycle: init, status, fix, deploy, health |
345
350
  | \`/docs\` | Browse, create, and verify permanent documentation |
346
351
  | \`/work\` | Task tracking: create, save, resume, complete |
347
- | \`/tutorial\` | Progressive learning path (7 core lessons + 9 modules) |
352
+ | \`/tutorial\` | Progressive learning path (21 items across 4 sections) |
348
353
 
349
354
  ## Skills
350
355
 
@@ -377,7 +382,7 @@ Do not store in \`.claude/memory/\`:
377
382
 
378
383
  ### Structure
379
384
 
380
- - \`memory/index.md\` is the root -- maps to topic files and subdirectories
385
+ - \`.claude/memory/index.md\` is the root -- maps to topic files and subdirectories
381
386
  - Every subdirectory has its own \`index.md\` mapping to children
382
387
  - Start at the root index and drill down
383
388
  - When a file outgrows a single document, split into a subdirectory
@@ -401,14 +406,14 @@ Read \`.claude/memory/profile/skills.md\` first. The \`automation\` skill level
401
406
  controls which docs you load and which lesson variant you deliver.
402
407
 
403
408
  **automation: none**
404
- - Load from \`reference/concepts/index.mdx\`: Glossary, What is a Workflow,
409
+ - Load from \`reference/concepts.mdx\`: Glossary, What is a Workflow,
405
410
  Platform Tools Overview only. Skip Zod, Execution Model, Design Decisions.
406
- - Load \`reference/deployment/command-center-ui.mdx\` for UI-first teaching.
411
+ - Load \`reference/deployment/command-center.mdx\` for UI-first teaching.
407
412
  - Do NOT load \`reference/resources/patterns.mdx\` or
408
413
  \`reference/platform-tools/adapters.mdx\` during core lessons.
409
414
 
410
415
  **automation: low-code**
411
- - Load all sections of \`reference/concepts/index.mdx\`.
416
+ - Load all sections of \`reference/concepts.mdx\`.
412
417
  - Load \`reference/resources/patterns.mdx\` with Zapier/Make mapping in mind.
413
418
  - Load \`reference/platform-tools/adapters.mdx\` on-demand (when tools are used).
414
419
 
@@ -496,7 +501,7 @@ Each lesson follows this flow:
496
501
 
497
502
  When automation is none:
498
503
  Skip the file tour. Start with what Elevasis does for their business -- use analogies
499
- from \`reference/developer/interaction-guidance.mdx\` (recipe, assembly line, kitchen
504
+ from \`reference/framework/interaction-guidance.mdx\` (recipe, assembly line, kitchen
500
505
  appliance). Explain deployment plainly: "You write the recipe here, then deploy it so
501
506
  it's live." Deploy the starter echo workflow (\`elevasis-sdk check\` + \`elevasis-sdk deploy\`),
502
507
  THEN tour the Command Center so the user sees populated pages, not empty ones. Tour:
@@ -744,14 +749,14 @@ Each module follows this flow:
744
749
  ## Modules
745
750
 
746
751
  **Module: hitl -- Human-in-the-Loop**
747
- Read: \`reference/deployment/command-center-ui.mdx\` (Command Queue section).
752
+ Read: \`reference/deployment/command-center.mdx\` (Command Queue section).
748
753
  Build: Add an approval gate using \`approval.requestApproval()\`. Test full lifecycle:
749
754
  trigger, see pending in Command Queue, approve/reject, observe resume.
750
755
  Key concepts: approval adapter, pending state, Command Queue UI, resume on decision.
751
756
  Verify: Trigger workflow, open Command Queue, approve, confirm completion.
752
757
 
753
758
  **Module: schedules -- Task Scheduling**
754
- Read: \`reference/deployment/command-center-ui.mdx\` (Task Scheduler section).
759
+ Read: \`reference/deployment/command-center.mdx\` (Task Scheduler section).
755
760
  Build: Create all three schedule types (Recurring cron, Relative delay, Absolute
756
761
  datetime). Use \`scheduler\` adapter for in-workflow scheduling.
757
762
  Key concepts: schedule types, cron syntax, scheduler adapter, Task Scheduler UI.
@@ -765,7 +770,7 @@ Verify: Run workflow, check notification in Command Center, confirm email receiv
765
770
 
766
771
  **Module: integrations -- Real-World Integrations**
767
772
  Read: \`reference/platform-tools/index.mdx\`, \`reference/platform-tools/adapters.mdx\`,
768
- \`reference/security/credentials.mdx\`.
773
+ \`reference/platform-tools/index.mdx\`.
769
774
  Build: Pick a real integration adapter based on user's goals (read \`identity.md\`).
770
775
  Set up credential (OAuth via UI, API key via CLI). Build end-to-end integration workflow.
771
776
  Key concepts: adapter pattern, credential scoping, error handling for external calls.
@@ -774,7 +779,7 @@ handling with invalid credential.
774
779
 
775
780
  **Module: error-handling -- Error Handling Mastery**
776
781
  Read: \`reference/resources/patterns.mdx\` (error handling),
777
- \`reference/troubleshooting/common-errors.mdx\`.
782
+ \`reference/troubleshooting.mdx\`.
778
783
  Build: Create a workflow demonstrating all three error types. Add try/catch,
779
784
  \`context.logger\`, and error recovery.
780
785
  Key concepts: ExecutionError, PlatformToolError, ToolingError, recovery patterns.
@@ -790,7 +795,7 @@ Key concepts: context.store, context.logger, domain organization, schema depth.
790
795
  Verify: Run workflow, confirm store values in step output, check logs in Execution Logs.
791
796
 
792
797
  **Module: composition -- Resource Composition**
793
- Read: \`reference/deployment/command-view.mdx\`, \`reference/resources/patterns.mdx\`.
798
+ Read: \`reference/deployment/command-center.mdx\`, \`reference/resources/patterns.mdx\`.
794
799
  Build: Create two workflows where the first triggers the second using
795
800
  \`execution.trigger()\`. Declare the relationship.
796
801
  Key concepts: execution.trigger, relationship declarations, Command View graph edges.
@@ -938,7 +943,7 @@ Last Session: {today's date}
938
943
  \`\`\`
939
944
 
940
945
  Update rules:
941
- - \`Current\`: free-form, e.g. "4: Using Platform Tools" or "M:integrations" or "20: Rules, Memory, and Customization"
946
+ - \`Current\`: free-form, e.g. "7: Using Platform Tools" or "M:integrations" or "20: Rules, Memory, and Customization"
942
947
  - \`Last Session\`: update to today's date on each \`/tutorial\` invocation
943
948
  - Completed Lessons: add a row when any numbered item (1-10, 20-21) finishes
944
949
  - Completed Modules: add a row when any module (items 11-19) finishes
@@ -1034,9 +1039,9 @@ by the \`<!-- initialized: false -->\` flag in CLAUDE.md, or run manually.
1034
1039
  - Create \`.claude/memory/profile/preferences.md\` (verbosity, guidance)
1035
1040
 
1036
1041
  4. **Git check**
1037
- - If \`.git/\` exists: note git is configured in memory/profile/preferences.md
1042
+ - If \`.git/\` exists: note git is configured in .claude/memory/profile/preferences.md
1038
1043
  - If \`.git/\` does not exist: suggest \`git init\` and optionally GitHub
1039
- - If git remote exists: note remote URL in memory/profile/preferences.md
1044
+ - If git remote exists: note remote URL in .claude/memory/profile/preferences.md
1040
1045
 
1041
1046
  5. **Verify project**
1042
1047
  Run \`elevasis-sdk check\` to confirm the starter resource is valid.
@@ -1057,9 +1062,9 @@ by the \`<!-- initialized: false -->\` flag in CLAUDE.md, or run manually.
1057
1062
 
1058
1063
  Display a project health summary:
1059
1064
  1. Template version (from elevasis.config.ts) and installed SDK version (from package.json). Suggest \`elevasis-sdk update\` to check for updates
1060
- 3. Profile summary (from memory/profile/skills.md)
1061
- 4. Quick drift check: count of missing managed files, missing gitignore entries
1062
- 5. Last deployment status (from memory/deployment-state.md if it exists)
1065
+ 2. Profile summary (from .claude/memory/profile/skills.md)
1066
+ 3. Quick drift check: count of missing managed files, missing gitignore entries
1067
+ 4. Last deployment status (from .claude/memory/deployment-state.md if it exists)
1063
1068
 
1064
1069
  ### \`/meta fix\` -- Maintenance and Upgrade
1065
1070
 
@@ -1077,9 +1082,9 @@ Detect and repair all drift. Optionally upgrades the SDK first.
1077
1082
  3. **CLAUDE.md sections:** Add missing sections in correct position
1078
1083
  4. **Memory structure:** Create base structure if missing, then verify index consistency.
1079
1084
  If \`.claude/memory/\` does not exist or is empty:
1080
- - Create \`memory/index.md\` (root index with placeholder entries)
1081
- - Create \`memory/errors/index.md\` (error category summary, empty tables)
1082
- - Create \`memory/errors/deploy.md\`, \`memory/errors/runtime.md\`, \`memory/errors/typescript.md\`
1085
+ - Create \`.claude/memory/index.md\` (root index with placeholder entries)
1086
+ - Create \`.claude/memory/errors/index.md\` (error category summary, empty tables)
1087
+ - Create \`.claude/memory/errors/deploy.md\`, \`.claude/memory/errors/runtime.md\`, \`.claude/memory/errors/typescript.md\`
1083
1088
  If memory exists, verify: every file referenced in an index exists; every file
1084
1089
  without an index entry gets one added; broken references are removed.
1085
1090
  5. **Documentation verification:** For each file in docs/:
@@ -1090,7 +1095,7 @@ Detect and repair all drift. Optionally upgrades the SDK first.
1090
1095
  e. Report discrepancies with suggested fixes
1091
1096
  Note: \`/docs verify\` is available for standalone interactive verification outside this pipeline.
1092
1097
  6. **Settings consistency:** Verify expected fields
1093
- 7. **Rules health:** Scan \`memory/errors/\` -- flag any entry that has recurred
1098
+ 7. **Rules health:** Scan \`.claude/memory/errors/\` -- flag any entry that has recurred
1094
1099
  3+ times and is not yet in \`.claude/rules/workspace-patterns.md\`.
1095
1100
  If \`workspace-patterns.md\` has no rules yet and 5+ resources exist in \`src/\`,
1096
1101
  suggest adding patterns. Surface suggestions only -- do not auto-generate.
@@ -1103,7 +1108,7 @@ Each step reports its result. Steps 1-8 run even if step 0 is skipped.
1103
1108
 
1104
1109
  ### \`/meta deploy\` -- Full Deploy Pipeline
1105
1110
 
1106
- 0. Read \`reference/deployment/command-view.mdx\` -- understand the Command View
1111
+ 0. Read \`reference/deployment/command-center.mdx\` -- understand the Command View
1107
1112
  model, relationship declarations, and what deploy-time validation checks.
1108
1113
  This context is essential for diagnosing validation failures in steps 1-2.
1109
1114
  1. Run \`elevasis-sdk check\` (validation)
@@ -1113,18 +1118,18 @@ Each step reports its result. Steps 1-8 run even if step 0 is skipped.
1113
1118
  5. Run \`elevasis-sdk deploy\`
1114
1119
  6. \`docs/project-map.mdx\` is auto-regenerated by deploy (no manual bump needed)
1115
1120
  7. Verify deployment via platform
1116
- 8. Update \`memory/deployment-state.md\` with count, timestamp, inventory
1121
+ 8. Update \`.claude/memory/deployment-state.md\` with count, timestamp, inventory
1117
1122
  9. If git configured and remote exists: optionally push
1118
1123
 
1119
1124
  Each step reports its result. Pipeline stops on failure with suggested fix.
1120
- If validation fails with relationship errors, re-read \`reference/deployment/command-view.mdx\`
1125
+ If validation fails with relationship errors, re-read \`reference/deployment/command-center.mdx\`
1121
1126
  for the enforcement model and common fixes.
1122
1127
 
1123
1128
  ### \`/meta health\` -- Execution Debugging
1124
1129
 
1125
1130
  Diagnose runtime failures and environment issues:
1126
1131
  - Show recent executions with status (completed/failed)
1127
- - For failed executions: analyze logs, cross-reference with memory/errors/
1132
+ - For failed executions: analyze logs, cross-reference with .claude/memory/errors/
1128
1133
  - Check resource deployment status (deployed, outdated, never deployed)
1129
1134
  - Verify environment: API key valid, credentials accessible, DB connected
1130
1135
 
@@ -1495,7 +1500,6 @@ Your \`ELEVASIS_PLATFORM_KEY\` in \`.env\` determines the organization.
1495
1500
  | --- | --- | --- |
1496
1501
  | \`api-key\` | \`{"apiKey": "sk-..."}\` | Stripe, Resend, Apify, Attio, Instantly |
1497
1502
  | \`webhook-secret\` | \`{"signingSecret": "whsec_..."}\` | Cal.com, Stripe webhooks |
1498
- | \`trello\` | \`{"apiKey": "...", "token": "..."}\` | Trello |
1499
1503
  | \`oauth\` | N/A (browser flow only) | Notion, Google Sheets, Dropbox |
1500
1504
 
1501
1505
  OAuth credentials **cannot** be created via CLI. Redirect the user to the Command Center UI.
@@ -1518,12 +1522,11 @@ elevasis-sdk creds list
1518
1522
  Display the output. Note which are \`oauth\` (not modifiable via CLI).
1519
1523
 
1520
1524
  **\`create\`:** Guided credential creation flow:
1521
- 1. Ask credential type (\`api-key\`, \`webhook-secret\`, or \`trello\`). Not \`oauth\`.
1525
+ 1. Ask credential type (\`api-key\` or \`webhook-secret\`). Not \`oauth\`.
1522
1526
  2. Ask credential name. Validate naming rules before proceeding.
1523
1527
  3. Ask the user to paste the credential value directly in chat.
1524
1528
  - For \`api-key\`: ask for the API key, construct \`{"apiKey": "..."}\`
1525
1529
  - For \`webhook-secret\`: ask for the signing secret, construct \`{"signingSecret": "..."}\`
1526
- - For \`trello\`: ask for API key AND user token, construct \`{"apiKey": "...", "token": "..."}\`
1527
1530
  4. Pipe to CLI: \`echo '{"apiKey":"..."}' | elevasis-sdk creds create --name {name} --type {type}\`
1528
1531
  5. Confirm success. **NEVER echo the credential value back.**
1529
1532
 
@@ -17,7 +17,6 @@ export { createNotionAdapter } from './notion.js';
17
17
  export { createResendAdapter } from './resend.js';
18
18
  export { createSignatureApiAdapter } from './signature-api.js';
19
19
  export { createStripeAdapter } from './stripe.js';
20
- export { createTrelloAdapter } from './trello.js';
21
20
  export { scheduler } from './scheduler.js';
22
21
  export { llm } from './llm.js';
23
22
  export { storage } from './storage.js';
@@ -2464,7 +2464,6 @@ You have control over session memory. Use memoryOps to manage critical informati
2464
2464
  **IMPORTANT - System-Managed Memory:**
2465
2465
  Do NOT update these keys via memoryOps (managed automatically by tools/actions):
2466
2466
  - notion-pages-cache (managed by Notion tools)
2467
- - trello-boards-cache (managed by Trello tools)
2468
2467
  - knowledge-map-state (managed by navigate-knowledge)
2469
2468
 
2470
2469
  Attempting to update system-managed keys will be rejected. Use tools to update their caches.
@@ -2877,6 +2876,14 @@ var AgentCancellationError = class extends ExecutionError {
2877
2876
  super(message, context);
2878
2877
  }
2879
2878
  };
2879
+ var AgentStalledError = class extends ExecutionError {
2880
+ type = "agent_stalled_error";
2881
+ severity = "critical";
2882
+ category = "agent";
2883
+ constructor(message, context) {
2884
+ super(message, context);
2885
+ }
2886
+ };
2880
2887
  var AgentMemoryValidationError = class extends ExecutionError {
2881
2888
  type = "agent_memory_validation_error";
2882
2889
  severity = "info";
@@ -3142,10 +3149,8 @@ var MEMORY_DOMAINS = {
3142
3149
  // Notion tools manage page hierarchy
3143
3150
  "github-repo-cache",
3144
3151
  // GitHub tools manage repository structure
3145
- "slack-channel-cache",
3152
+ "slack-channel-cache"
3146
3153
  // Slack tools manage channel data
3147
- "trello-boards-cache"
3148
- // Trello tools manage boards/lists/cards
3149
3154
  ],
3150
3155
  /**
3151
3156
  * Action-owned keys
@@ -3972,9 +3977,7 @@ async function reloadKnowledgeMapTools(knowledgeMap, memory, context) {
3972
3977
  function initializeKnowledgeMap(knowledgeMap) {
3973
3978
  if (!knowledgeMap) return void 0;
3974
3979
  return {
3975
- nodes: Object.fromEntries(
3976
- Object.entries(knowledgeMap.nodes).map(([id, node]) => [id, { ...node }])
3977
- )
3980
+ nodes: Object.fromEntries(Object.entries(knowledgeMap.nodes).map(([id, node]) => [id, { ...node }]))
3978
3981
  };
3979
3982
  }
3980
3983
  var Agent = class {
@@ -4213,13 +4216,20 @@ var Agent = class {
4213
4216
  while (iteration <= maxIterations) {
4214
4217
  if (context.signal?.aborted) {
4215
4218
  if (context.signal.reason === "timeout") {
4216
- throw new AgentTimeoutError(
4217
- `Agent execution exceeded timeout (${this.config.constraints?.timeout}ms)`,
4218
- { timeout: this.config.constraints?.timeout ?? 0, iteration }
4219
- );
4219
+ throw new AgentTimeoutError(`Agent execution exceeded timeout (${this.config.constraints?.timeout}ms)`, {
4220
+ timeout: this.config.constraints?.timeout ?? 0,
4221
+ iteration
4222
+ });
4223
+ }
4224
+ if (context.signal.reason === "stalled") {
4225
+ throw new AgentStalledError("Execution stalled: no heartbeat received within threshold", { iteration });
4220
4226
  }
4221
4227
  throw new AgentCancellationError("Execution cancelled by user", { iteration });
4222
4228
  }
4229
+ try {
4230
+ await context.onHeartbeat?.();
4231
+ } catch {
4232
+ }
4223
4233
  const result = await this.runIteration(iteration, context);
4224
4234
  if (result.shouldComplete) {
4225
4235
  return;
@@ -4372,14 +4382,11 @@ var Agent = class {
4372
4382
  const finalOutput = this.contract.outputSchema.parse(retryOutput);
4373
4383
  return { output: finalOutput, attempts: 2 };
4374
4384
  } catch (error) {
4375
- throw new AgentOutputValidationError(
4376
- "Agent output validation failed after retry",
4377
- {
4378
- agentId: this.config.resourceId,
4379
- attempts: 2,
4380
- zodError: error instanceof ZodError ? error.format() : error
4381
- }
4382
- );
4385
+ throw new AgentOutputValidationError("Agent output validation failed after retry", {
4386
+ agentId: this.config.resourceId,
4387
+ attempts: 2,
4388
+ zodError: error instanceof ZodError ? error.format() : error
4389
+ });
4383
4390
  }
4384
4391
  }
4385
4392
  /**
@@ -4397,12 +4404,17 @@ var Agent = class {
4397
4404
  try {
4398
4405
  this.logger.action(actionType, `${actionType} started`, 0, generationStartTime, generationStartTime, 0);
4399
4406
  const attempt = actionType === "output-generation" ? 1 : 2;
4400
- const adapter = this.adapterFactory(this.modelConfig, this.executionContext?.aiUsageCollector, "agent-completion", {
4401
- type: "agent-completion",
4402
- attempt,
4403
- sessionId: this.executionContext?.sessionId,
4404
- turnNumber: this.executionContext?.sessionTurnNumber
4405
- });
4407
+ const adapter = this.adapterFactory(
4408
+ this.modelConfig,
4409
+ this.executionContext?.aiUsageCollector,
4410
+ "agent-completion",
4411
+ {
4412
+ type: "agent-completion",
4413
+ attempt,
4414
+ sessionId: this.executionContext?.sessionId,
4415
+ turnNumber: this.executionContext?.sessionTurnNumber
4416
+ }
4417
+ );
4406
4418
  const structuredOutput = await callLLMForAgentCompletion(adapter, {
4407
4419
  systemPrompt,
4408
4420
  memoryContext: this.memoryManager.toContext(this.iterationNumber, this.executionContext?.sessionTurnNumber),
@@ -4885,23 +4897,6 @@ function createStripeAdapter(credential) {
4885
4897
  return createAdapter("stripe", METHODS11, credential);
4886
4898
  }
4887
4899
 
4888
- // src/worker/adapters/trello.ts
4889
- var METHODS12 = [
4890
- "getBoard",
4891
- "getLists",
4892
- "getCards",
4893
- "createCard",
4894
- "updateCard",
4895
- "createList",
4896
- "createChecklist",
4897
- "addChecklistItem",
4898
- "updateChecklistItem",
4899
- "getCardChecklists"
4900
- ];
4901
- function createTrelloAdapter(credential) {
4902
- return createAdapter("trello", METHODS12, credential);
4903
- }
4904
-
4905
4900
  // src/worker/adapters/scheduler.ts
4906
4901
  var scheduler = createAdapter("scheduler", [
4907
4902
  "createSchedule",
@@ -5150,19 +5145,12 @@ function buildWorkerExecutionContext(params) {
5150
5145
  };
5151
5146
  }
5152
5147
  function startWorker(org) {
5153
- const workflows = new Map(
5154
- (org.workflows ?? []).map((w) => [w.config.resourceId, w])
5155
- );
5156
- const agents = new Map(
5157
- (org.agents ?? []).map((a) => [a.config.resourceId, a])
5158
- );
5148
+ const workflows = new Map((org.workflows ?? []).map((w) => [w.config.resourceId, w]));
5149
+ const agents = new Map((org.agents ?? []).map((a) => [a.config.resourceId, a]));
5159
5150
  let localAbortController = new AbortController();
5160
5151
  console.log(`[SDK-WORKER] Worker started with ${workflows.size} workflow(s), ${agents.size} agent(s)`);
5161
5152
  parentPort.on("message", async (msg) => {
5162
5153
  if (msg.type === "manifest") {
5163
- const workflowList = (org.workflows ?? []).map((w) => w.config.resourceId);
5164
- const agentList = (org.agents ?? []).map((a) => a.config.resourceId);
5165
- console.log(`[SDK-WORKER] Manifest requested: workflows=[${workflowList.join(", ")}], agents=[${agentList.join(", ")}]`);
5166
5154
  parentPort.postMessage({
5167
5155
  type: "manifest",
5168
5156
  workflows: (org.workflows ?? []).map((w) => ({
@@ -5244,7 +5232,13 @@ function startWorker(org) {
5244
5232
  } catch (err) {
5245
5233
  const durationMs = Date.now() - startTime;
5246
5234
  console.error(`[SDK-WORKER] Workflow '${resourceId}' failed (${durationMs}ms): ${String(err)}`);
5247
- parentPort.postMessage({ type: "result", status: "failed", error: String(err), logs: [], metrics: { durationMs } });
5235
+ parentPort.postMessage({
5236
+ type: "result",
5237
+ status: "failed",
5238
+ error: String(err),
5239
+ logs: [],
5240
+ metrics: { durationMs }
5241
+ });
5248
5242
  }
5249
5243
  return;
5250
5244
  }
@@ -5321,4 +5315,4 @@ function startWorker(org) {
5321
5315
  });
5322
5316
  }
5323
5317
 
5324
- export { PlatformToolError, approval, createAdapter, createApifyAdapter, createAttioAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createInstantlyAdapter, createMailsoAdapter, createNotionAdapter, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, createTrelloAdapter, email, execution, lead, llm, notifications, pdf, platform, scheduler, startWorker, storage };
5318
+ export { PlatformToolError, approval, createAdapter, createApifyAdapter, createAttioAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createInstantlyAdapter, createMailsoAdapter, createNotionAdapter, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, email, execution, lead, llm, notifications, pdf, platform, scheduler, startWorker, storage };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elevasis/sdk",
3
- "version": "0.5.12",
3
+ "version": "0.5.14",
4
4
  "description": "SDK for building Elevasis organization resources",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,6 +1,6 @@
1
1
  # SDK Reference Navigation
2
2
 
3
- Auto-generated from reference file frontmatter. 32 files indexed.
3
+ Auto-generated from reference file frontmatter. 28 files indexed.
4
4
 
5
5
  All paths are relative to `node_modules/@elevasis/sdk/reference/`.
6
6
 
@@ -8,58 +8,39 @@ All paths are relative to `node_modules/@elevasis/sdk/reference/`.
8
8
 
9
9
  | Resource | Location | Description | When to Load |
10
10
  | --- | --- | --- | --- |
11
+ | CLI Reference | `cli.mdx` | Full reference for every elevasis-sdk CLI command -- scaffold, validate, deploy, execute, and inspect resources | Running CLI operations |
12
+ | Concepts Reference | `concepts.mdx` | Plain-English explanations of Elevasis SDK concepts -- glossary, workflow analogies, Zod schemas, execution model, platform tools, common errors, and design decisions | User asks what is or needs conceptual grounding |
13
+ | Getting Started | `getting-started.mdx` | Install the Elevasis SDK, scaffold a project, and run your first deployment | Setting up a new project or onboarding |
11
14
  | Elevasis SDK | `index.mdx` | Build and deploy workflows, agents, and resources with the Elevasis SDK | First session or new to the SDK |
12
-
13
- ## Cli
14
-
15
- | Resource | Location | Description | When to Load |
16
- | --- | --- | --- | --- |
17
- | CLI Reference | `cli/index.mdx` | Full reference for every elevasis-sdk CLI command -- scaffold, validate, deploy, execute, and inspect resources | Running CLI operations |
18
-
19
- ## Concepts
20
-
21
- | Resource | Location | Description | When to Load |
22
- | --- | --- | --- | --- |
23
- | Concepts Reference | `concepts/index.mdx` | Plain-English explanations of Elevasis SDK concepts -- glossary, workflow analogies, Zod schemas, execution model, platform tools, common errors, and design decisions | User asks what is or needs conceptual grounding |
15
+ | Roadmap | `roadmap.mdx` | Planned SDK features -- error taxonomy, retry semantics, circuit breaker, metrics, alerting, and resource lifecycle extensions | Asking about future features or planned capabilities |
16
+ | Execution Runtime | `runtime.mdx` | How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, observability, resource limits, and v1 limitations | Debugging execution behavior or understanding the runtime model |
17
+ | Common Errors | `troubleshooting.mdx` | Static SDK-level error catalog -- CLI errors, deployment errors, schema validation, platform tool failures, and runtime errors with diagnostic steps | Debugging an unknown error not found in workspace memory |
24
18
 
25
19
  ## Deployment
26
20
 
27
21
  | Resource | Location | Description | When to Load |
28
22
  | --- | --- | --- | --- |
29
23
  | Execution API | `deployment/api.mdx` | REST endpoints for executing resources, querying execution history, and managing deployments via the Elevasis external API | Calling the API directly or debugging API responses |
30
- | Command Center UI | `deployment/command-center-ui.mdx` | Reference for the Elevasis Command Center -- what each page does, when to use it post-deployment, and how SDK concepts map to UI actions | User asks about the Command Center UI, post-deployment workflow, or monitoring deployed resources |
31
- | Command View | `deployment/command-view.mdx` | How the Command View graph works -- node types, relationships, what is enforced vs decorative, and what the platform needs to render your resource graph | Deploying resources or building resources that invoke other resources |
24
+ | Command Center | `deployment/command-center.mdx` | Post-deployment UI reference -- what each page does, the resource graph model, relationships, validation, and how SDK concepts map to Command Center actions | User asks about the Command Center UI, post-deployment workflow, monitoring, or the resource graph |
32
25
  | Deploying Resources | `deployment/index.mdx` | How to deploy your Elevasis SDK resources to the platform using elevasis-sdk deploy, including configuration, validation, and environment setup | Preparing to deploy or debugging deploy failures |
33
26
 
34
- ## Developer
35
-
36
- | Resource | Location | Description | When to Load |
37
- | --- | --- | --- | --- |
38
- | Interaction Guidance | `developer/interaction-guidance.mdx` | Full dimensional adaptation rules per skill axis -- platform navigation, API integration, automation concepts, domain expertise -- with growth tracking protocol | Unsure how to adapt for a skill combination |
39
-
40
27
  ## Framework
41
28
 
42
29
  | Resource | Location | Description | When to Load |
43
30
  | --- | --- | --- | --- |
44
31
  | Agent System | `framework/agent.mdx` | CLAUDE.md drives all agent behavior -- project instructions, slash commands, memory-based developer profile, and three-tier adaptive guidance | Configuring agent behavior or capabilities |
45
- | Resource Documentation | `framework/documentation.mdx` | Write and deploy MDX documentation alongside your Elevasis resources | Writing or updating project documentation |
46
- | Development Framework | `framework/index.mdx` | The SDK scaffolds a complete development environment for Claude Code -- project instructions, slash commands, cross-session memory, and template versioning | Understanding the agent framework structure |
32
+ | Development Framework | `framework/index.mdx` | The SDK scaffolds a complete development environment for Claude Code -- project instructions, slash commands, cross-session memory, template versioning, and resource documentation | Understanding the agent framework structure |
33
+ | Interaction Guidance | `framework/interaction-guidance.mdx` | Full dimensional adaptation rules per skill axis -- platform navigation, API integration, automation concepts, domain expertise -- with growth tracking protocol | Unsure how to adapt for a skill combination |
47
34
  | Memory System | `framework/memory.mdx` | Cross-session project knowledge stored in .claude/memory/ -- deployment state, environment, decisions, and error patterns that persist between Claude Code sessions | Working with agent memory or session state |
48
35
  | Project Structure | `framework/project-structure.mdx` | Each file scaffolded by elevasis-sdk init and its purpose in the development workflow | Understanding scaffolded files or project layout |
49
-
50
- ## Getting-started
51
-
52
- | Resource | Location | Description | When to Load |
53
- | --- | --- | --- | --- |
54
- | Getting Started | `getting-started/index.mdx` | Install the Elevasis SDK, scaffold a project, and run your first deployment | Setting up a new project or onboarding |
36
+ | Tutorial System | `framework/tutorial-system.mdx` | Reference for the SDK tutorial system -- 21-item menu across 4 sections, skill-level adaptation rules, progress tracking format, and per-lesson module contents | (not specified) |
55
37
 
56
38
  ## Platform-tools
57
39
 
58
40
  | Resource | Location | Description | When to Load |
59
41
  | --- | --- | --- | --- |
60
- | Typed Adapters | `platform-tools/adapters.mdx` | Type-safe wrappers over platform.call() for all integrations and platform tools -- Attio, Stripe, Notion, Google Sheets, Trello, and more -- with full autocomplete, compile-time checking, and zero boilerplate | Using typed adapters instead of raw platform.call(), or needs to know what adapter methods are available |
61
- | Integration Examples | `platform-tools/examples.mdx` | Working code examples for email, CRM, PDF, LLM inference, resource triggering, and storage using typed adapters and platform.call() | Implementing a platform tool call in a workflow step |
62
- | Platform Tools | `platform-tools/index.mdx` | Access 70+ tools across integration adapters and platform services from your SDK workflows -- typed adapters with full autocomplete for all tools, plus platform.call() as a fallback | Connecting to external services |
42
+ | Typed Adapters | `platform-tools/adapters.mdx` | Type-safe wrappers over platform.call() for all integrations and platform tools -- Attio, Stripe, Notion, Google Sheets, and more -- with full autocomplete, compile-time checking, and zero boilerplate | Using typed adapters instead of raw platform.call(), or needs to know what adapter methods are available |
43
+ | Platform Tools | `platform-tools/index.mdx` | Access 70+ tools across integration adapters and platform services from your SDK workflows -- typed adapters, credential security model, and working code examples | Connecting to external services |
63
44
 
64
45
  ## Resources
65
46
 
@@ -69,25 +50,6 @@ All paths are relative to `node_modules/@elevasis/sdk/reference/`.
69
50
  | Common Patterns | `resources/patterns.mdx` | Common resource patterns for Elevasis SDK developers -- sequential steps, conditional branching, platform tools, error handling, and resource status management | Building or modifying a workflow |
70
51
  | SDK Types | `resources/types.mdx` | Complete type reference for @elevasis/sdk -- package exports, re-exported platform types, ElevasConfig interface, StepHandler context, and runtime values | Looking up type signatures or SDK exports |
71
52
 
72
- ## Roadmap
73
-
74
- | Resource | Location | Description | When to Load |
75
- | --- | --- | --- | --- |
76
- | Roadmap | `roadmap/index.mdx` | Planned SDK features -- error taxonomy, retry semantics, circuit breaker, metrics, alerting, and resource lifecycle extensions | Asking about future features or planned capabilities |
77
-
78
- ## Runtime
79
-
80
- | Resource | Location | Description | When to Load |
81
- | --- | --- | --- | --- |
82
- | Execution Runtime | `runtime/index.mdx` | How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, and observability | Debugging execution behavior or understanding the runtime model |
83
- | Resource Limits & Quotas | `runtime/limits.mdx` | Memory limits, execution timeouts, scale quotas, networking constraints, and v1 platform limitations for SDK resources | Hitting resource limits or planning for scale |
84
-
85
- ## Security
86
-
87
- | Resource | Location | Description | When to Load |
88
- | --- | --- | --- | --- |
89
- | Credential Security | `security/credentials.mdx` | Three-layer credential model: platform tools (server-side injection), http tool (arbitrary APIs), getCredential() (explicit opt-in raw access) -- .env scope and security boundaries | Setting up integrations or configuring tool access |
90
-
91
53
  ## Templates
92
54
 
93
55
  | Resource | Location | Description | When to Load |
@@ -99,9 +61,3 @@ All paths are relative to `node_modules/@elevasis/sdk/reference/`.
99
61
  | Template: Recurring Job | `templates/recurring-job.mdx` | Scheduler-triggered periodic workflow -- run a task on a schedule (daily, weekly, hourly, or custom cron) | Applying the recurring-job workflow template |
100
62
  | Template: Text Classifier | `templates/text-classifier.mdx` | Multi-label text classification with structured output -- classify text into predefined categories using an LLM with JSON output | Applying the text-classifier workflow template |
101
63
  | Template: Web Scraper | `templates/web-scraper.mdx` | Apify-based web scraper that stores results in Supabase -- fetch structured data from any website via Apify actors | Applying the web-scraper workflow template |
102
-
103
- ## Troubleshooting
104
-
105
- | Resource | Location | Description | When to Load |
106
- | --- | --- | --- | --- |
107
- | Common Errors | `troubleshooting/common-errors.mdx` | Static SDK-level error catalog -- CLI errors, deployment errors, schema validation, platform tool failures, and runtime errors with diagnostic steps | Debugging an unknown error not found in workspace memory |