@elevasis/sdk 0.4.16 → 0.5.0

package/reference/resources/index.mdx

@@ -23,7 +23,7 @@ A complete workflow definition has four required properties:
 
 ```typescript
 import { z } from 'zod';
-import type { WorkflowDefinition, OrganizationResources } from '@elevasis/sdk';
+import type { WorkflowDefinition } from '@elevasis/sdk';
 
 const echoInput = z.object({
   message: z.string(),
@@ -34,21 +34,32 @@ const echoOutput = z.object({
 });
 
 type EchoInput = z.infer<typeof echoInput>;
-type EchoOutput = z.infer<typeof echoOutput>;
 
 const echoWorkflow: WorkflowDefinition = {
   config: {
-    name: 'echo',
+    resourceId: 'echo',
+    name: 'Echo',
+    type: 'workflow',
     description: 'Returns the input message unchanged',
+    version: '1.0.0',
     status: 'dev',
   },
   contract: {
-    input: echoInput,
-    output: echoOutput,
+    inputSchema: echoInput,
+    outputSchema: echoOutput,
   },
   steps: {
-    run: async (input: EchoInput): Promise<EchoOutput> => {
-      return { result: input.message };
+    run: {
+      id: 'run',
+      name: 'Run',
+      description: 'Returns the input message unchanged',
+      handler: async (input) => {
+        const { message } = input as EchoInput;
+        return { result: message };
+      },
+      inputSchema: echoInput,
+      outputSchema: echoOutput,
+      next: null,
     },
   },
   entryPoint: 'run',
@@ -61,23 +72,27 @@ The `config` block identifies the workflow on the platform:
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `name` | `string` | Unique name within your organization. Used by the CLI and platform UI. |
-| `description` | `string` | Human-readable summary shown in the dashboard. |
-| `status` | `'dev' | 'production'` | Controls availability. Use `'dev'` while building. See [Resource Status](#resource-status). |
+| `resourceId` | `string` | Unique lowercase ID within your organization (e.g., `send-welcome-email`). Used by the CLI to target this resource. |
+| `name` | `string` | Human-readable display name shown in the dashboard. |
+| `type` | `'workflow'` | Always the literal string `'workflow'` for workflow resources. |
+| `description` | `string` | Summary shown in the dashboard and command center. |
+| `version` | `string` | Semver string (e.g., `'1.0.0'`). Increment when making breaking changes to the contract. |
+| `status` | `'dev' | 'prod'` | Controls availability. Use `'dev'` while building. See [Resource Status](#resource-status). |
+| `domains` | `string[]` | Optional. Groups resources in the command center view. |
 
 ### contract
 
-The `contract` block defines the Zod schemas for input and output. The platform validates input against `contract.input` before passing it to your step handler, and validates the step's return value against `contract.output`.
+The `contract` block defines the Zod schemas for input and output. The platform validates input against `contract.inputSchema` before passing it to your entry step handler, and validates the final step's return value against `contract.outputSchema`.
 
-Always use `z.object()` for both schemas. Use `z.infer` to derive TypeScript types from the schemas -- this keeps types and runtime validation in sync automatically.
+Always use `z.object()` for both schemas. Use `z.infer` to derive TypeScript types -- this keeps types and runtime validation in sync automatically.
 
 ```typescript
 const contract = {
-  input: z.object({
+  inputSchema: z.object({
     userId: z.string().uuid(),
     action: z.string(),
   }),
-  output: z.object({
+  outputSchema: z.object({
     success: z.boolean(),
     message: z.string(),
   }),
@@ -86,17 +101,31 @@ const contract = {
 
 ### steps
 
-The `steps` record maps step names to handler functions. Each handler receives the validated input and an optional `StepContext` (execution metadata). Single-step workflows have one entry; multi-step workflows have one entry per step.
+The `steps` record maps step IDs to step objects. Each step has metadata (`id`, `name`, `description`), a `handler` function, Zod schemas for its own input and output, and a `next` property that controls routing.
 
 ```typescript
 const steps = {
-  validate: async (input: MyInput) => {
-    // first step -- returns output to pass to next step
-    return { validated: true, data: input };
+  validate: {
+    id: 'validate',
+    name: 'Validate',
+    description: 'Validates the incoming request',
+    handler: async (input: MyInput) => {
+      return { validated: true, data: input };
+    },
+    inputSchema: myInputSchema,
+    outputSchema: z.object({ validated: z.boolean(), data: myInputSchema }),
+    next: { target: 'process' }, // points to the next step
   },
-  process: async (input: ValidatedData) => {
-    // second step
-    return { result: 'done' };
+  process: {
+    id: 'process',
+    name: 'Process',
+    description: 'Processes the validated data',
+    handler: async (input: ValidatedData) => {
+      return { result: 'done' };
+    },
+    inputSchema: z.object({ validated: z.boolean(), data: myInputSchema }),
+    outputSchema: z.object({ result: z.string() }),
+    next: null, // terminal step
   },
 };
 ```
@@ -124,29 +153,43 @@ Use `StepType.LINEAR` to connect steps in a fixed sequence. Each step declares a
 
 ```typescript
 import { z } from 'zod';
-import { StepType } from '@elevasis/sdk';
 import type { WorkflowDefinition, WorkflowStep } from '@elevasis/sdk';
 
 const fetchStep: WorkflowStep = {
-  type: StepType.LINEAR,
+  id: 'fetch',
+  name: 'Fetch',
+  description: 'Fetches the raw data',
   handler: async (input) => {
-    const data = await fetchSomething(input.id);
+    const data = await fetchSomething((input as { id: string }).id);
     return { data };
   },
+  inputSchema: z.object({ id: z.string() }),
+  outputSchema: z.object({ data: z.unknown() }),
   next: { target: 'process' },
 };
 
 const processStep: WorkflowStep = {
-  type: StepType.LINEAR,
+  id: 'process',
+  name: 'Process',
+  description: 'Transforms the fetched data',
   handler: async (input) => {
-    return { result: transform(input.data) };
+    return { result: transform((input as { data: unknown }).data) };
   },
+  inputSchema: z.object({ data: z.unknown() }),
+  outputSchema: z.object({ result: z.string() }),
   next: null, // terminal step
 };
 
 const pipeline: WorkflowDefinition = {
-  config: { name: 'pipeline', description: 'Fetch then process', status: 'dev' },
-  contract: { input: pipelineInput, output: pipelineOutput },
+  config: {
+    resourceId: 'pipeline',
+    name: 'Pipeline',
+    type: 'workflow',
+    description: 'Fetch then process',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: { inputSchema: pipelineInput, outputSchema: pipelineOutput },
   steps: { fetch: fetchStep, process: processStep },
   entryPoint: 'fetch',
 };
@@ -157,23 +200,27 @@ const pipeline: WorkflowDefinition = {
 Use `StepType.CONDITIONAL` to route to different steps based on output values. Each route has a `condition` function and a `target` step name. The first condition that returns `true` wins. A `defaultTarget` is required as a fallback.
 
 ```typescript
-import { StepType } from '@elevasis/sdk';
+import { z } from 'zod';
 import type { WorkflowStep } from '@elevasis/sdk';
 
 const routerStep: WorkflowStep = {
-  type: StepType.CONDITIONAL,
+  id: 'router',
+  name: 'Router',
+  description: 'Scores the input and routes to the appropriate path',
   handler: async (input) => {
     const score = await evaluate(input);
     return { score };
   },
+  inputSchema: z.object({ value: z.unknown() }),
+  outputSchema: z.object({ score: z.number() }),
   next: {
     routes: [
       {
-        condition: (output) => output.score \>= 80,
+        condition: (output) => (output as { score: number }).score \>= 80,
         target: 'highScorePath',
       },
       {
-        condition: (output) => output.score \>= 50,
+        condition: (output) => (output as { score: number }).score \>= 50,
         target: 'mediumScorePath',
       },
     ],
@@ -219,7 +266,7 @@ const myStep: StepHandler = async (input, context) => {
 
 Agents are autonomous resources that use an LLM and tools to complete a goal. You define them with `AgentDefinition`.
 
-**Note:** Agent execution in the worker runtime is not yet fully supported. Defining agents is supported for forward compatibility, but executions will return a failure response until agent execution ships.
+**Note:** Use `elevasis exec --async` when executing agents. Agents can run for minutes or longer, and the synchronous execute endpoint will time out for long-running runs. The `--async` flag returns an execution ID immediately and polls for the result.
 
 ```typescript
 import type { AgentDefinition } from '@elevasis/sdk';