@elevasis/sdk 1.43.0 → 1.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -59,8 +59,8 @@
     "typescript": "5.9.2",
     "zod": "^4.1.0",
     "@repo/core": "0.58.0",
-    "@repo/typescript-config": "0.0.0",
-    "@repo/eslint-config": "0.0.0"
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
   },
   "scripts": {
     "lint": "eslint src --max-warnings 0",

package/reference/sdk/resources/index.mdx

@@ -271,28 +271,63 @@ Agents are autonomous resources that use an LLM and tools to complete a goal. Yo
 
 **Note:** Use `elevasis-sdk 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.
 
+There is no separate `agentConfig` object — agent-specific fields (`kind`, `systemPrompt`, `constraints`, `sessionCapable`, `securityLevel`, `memoryPreferences`) live directly on `config`, alongside the same identity fields a `WorkflowDefinition` uses. `modelConfig` is a sibling of `config`, not nested inside it. `kind` and `contract` are both required.
+
+This example is a minimal single-shot (non-session) agent: one question in, one structured answer out. It is type-checked against the published `@elevasis/sdk` on every `pnpm check:docs-snippets` run — see `operations/src/example/example-agent.ts` in a scaffolded project for the working, OM-descriptor-bound copy (`resourceId` there derives from the OM Resource descriptor, same as the workflow example above; this version inlines the id directly to keep the snippet self-contained).
+
+{/* doc-snippet:start:agent-definition-example */}
+
 ```typescript
 import type { AgentDefinition } from '@elevasis/sdk';
-import { resourceDescriptors } from '@core/config/organization-model';
+import { z } from 'zod';
+
+const inputSchema = z.object({
+  question: z.string().min(1),
+});
+const outputSchema = z.object({
+  answer: z.string(),
+  confidence: z.enum(['high', 'medium', 'low']),
+});
 
 const myAgent: AgentDefinition = {
   config: {
-    resource: resourceDescriptors.myAgent,
-    resourceId: resourceDescriptors.myAgent.id,
-    name: 'my-agent',
-    type: resourceDescriptors.myAgent.kind,
-    description: 'Answers questions using platform tools',
+    resourceId: 'my-agent',
+    name: 'My Agent',
+    description: 'Answers a single question with a structured, confidence-rated response.',
+    type: 'agent',
+    kind: 'utility',
+    version: '1.0.0',
     status: 'dev',
+    systemPrompt:
+      'You answer a single question directly and concisely. State your confidence honestly.',
   },
-  agentConfig: {
-    model: { provider: 'openai', model: 'gpt-5' },
-    systemPrompt: 'You are a helpful assistant.',
-    maxIterations: 10,
-  },
+  contract: { inputSchema, outputSchema },
   tools: [],
+  modelConfig: {
+    provider: 'anthropic',
+    model: 'claude-sonnet-5',
+    apiKey: process.env.ANTHROPIC_API_KEY ?? '',
+  },
 };
 ```
 
+{/* doc-snippet:end:agent-definition-example */}
+
+### config (agent-specific fields)
+
+| Field               | Type                                                                               | Description                                                                                                                                                            |
+| ------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kind`              | `'orchestrator' | 'specialist' | 'utility' | 'platform'`                        | Required. What role this agent plays — not enforced at runtime today, but tenant-authored and validated at deploy against your OM resource descriptor's own `kind`.    |
+| `systemPrompt`      | `string`                                                                           | Required. The agent's base system prompt.                                                                                                                              |
+| `constraints`       | `{ maxIterations?, timeout?, maxSessionMemoryKeys?, maxMemoryTokens? }` (optional) | Iteration budget, execution timeout in ms, and session-memory limits.                                                                                                  |
+| `sessionCapable`    | `boolean` (optional)                                                               | Opt in to multi-turn sessions. Defaults to `false` — the shape used in the example above, which completes and returns `contract.outputSchema` in a single turn.        |
+| `securityLevel`     | `'standard' | 'hardened' | 'none'` (optional)                                    | Prompt-hardening tier. Auto-derived from `sessionCapable` when omitted (`true` → `'hardened'`, `false` → `'standard'`). Never set `'none'` on a session-capable agent. |
+| `memoryPreferences` | `string` (optional)                                                                | Guidance injected into the system prompt when session memory management is enabled.                                                                                    |
+
+### contract (agent)
+
+`contract.inputSchema` is required, same as a workflow. `contract.outputSchema` is what a **non-session** (single-shot) agent like the example above returns — there is no conversational reply to read a structured answer from otherwise. A `sessionCapable: true` agent typically omits `outputSchema` and speaks through its conversational `message` instead.
+
 ---
 
 ## DeploymentSpec

package/reference/sdk/resources/types.mdx

@@ -59,20 +59,20 @@ config: {
 
 ## Execution Types
 
-| Type                 | Description                                                                    |
-| -------------------- | ------------------------------------------------------------------------------ |
-| `WorkflowDefinition` | Complete workflow definition including config, contract, steps, and entryPoint |
-| `WorkflowStep`       | Individual step definition with type, handler, and next routing                |
-| `WorkflowConfig`     | Metadata block: name, description, status, links, category                     |
-| `StepHandler`        | Function type: `(input: unknown, context: StepContext) => Promise<unknown>`    |
-| `NextConfig`         | Union of `LinearNext` and `ConditionalNext`                                    |
-| `LinearNext`         | Fixed next step routing                                                        |
-| `ConditionalNext`    | Branching step routing                                                         |
-| `StepType`           | Runtime enum for step routing                                                  |
-| `AgentDefinition`    | Complete agent definition including config, agentConfig, and tools             |
-| `ExecutionContext`   | Runtime context passed to step handlers                                        |
-| `ExecutionMetadata`  | Metadata about a running execution                                             |
-| `ExecutionInterface` | Interface for triggering and inspecting executions                             |
+| Type                 | Description                                                                                                                                             |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WorkflowDefinition` | Complete workflow definition including config, contract, steps, and entryPoint                                                                          |
+| `WorkflowStep`       | Individual step definition with type, handler, and next routing                                                                                         |
+| `WorkflowConfig`     | Metadata block: name, description, status, links, category                                                                                              |
+| `StepHandler`        | Function type: `(input: unknown, context: StepContext) => Promise<unknown>`                                                                             |
+| `NextConfig`         | Union of `LinearNext` and `ConditionalNext`                                                                                                             |
+| `LinearNext`         | Fixed next step routing                                                                                                                                 |
+| `ConditionalNext`    | Branching step routing                                                                                                                                  |
+| `StepType`           | Runtime enum for step routing                                                                                                                           |
+| `AgentDefinition`    | Complete agent definition: `config` (agent-specific fields live here directly, not in a separate `agentConfig`), `contract`, `tools`, and `modelConfig` |
+| `ExecutionContext`   | Runtime context passed to step handlers                                                                                                                 |
+| `ExecutionMetadata`  | Metadata about a running execution                                                                                                                      |
+| `ExecutionInterface` | Interface for triggering and inspecting executions                                                                                                      |
 
 ## ElevasConfig