@elevasis/sdk 1.43.0 → 1.44.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.43.0",
+  "version": "1.44.1",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -58,9 +58,9 @@
     "tsup": "^8.0.0",
     "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/core": "0.59.0",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
   },
   "scripts": {
     "lint": "eslint src --max-warnings 0",

package/reference/claude-config/sync-notes/2026-08-02-auth-guard-defaults-and-truncation-fix.md

@@ -0,0 +1,122 @@
+# Your auth guards now wait for organization context, and truncated tool results stay valid JSON
+
+## Why this note exists
+
+This train publishes all three packages at once — `@elevasis/core`, `@elevasis/ui`, and
+`@elevasis/sdk`. Four of the changes are things you can observe without changing a line of your own
+code, which is exactly why they are worth reading before you take the baseline bump.
+
+**1. `ProtectedRoute` now waits for organization context by default.** This is the one behavior
+change most likely to surprise you, because nothing in your project asked for it.
+
+Until now the default value of `waitForOrganization` depended on which import path a route file
+happened to use. Routes importing the guard from `@elevasis/ui/features/auth` defaulted to `false`
+and rendered before organization context existed; routes importing from `@elevasis/ui/auth`
+defaulted to `true` and waited. One application, two guard behaviors, decided by an import
+specifier. Both defaults are now `true`, resolved through a single shared predicate.
+
+We audited every template-family project before shipping this rather than assuming it was safe.
+Between 8 and 9 routes per project are affected — `index.tsx`, `knowledge.tsx`, and every
+`settings/*.tsx` — and **not one route in any project passes the prop explicitly**. Every affected
+route is organization-scoped, so none of them has a legitimate reason to render before organization
+context arrives. The measurable cost is that `settings/appearance.tsx` and `settings/account.tsx`
+are user-scoped and will now wait marginally longer than they strictly need to. That is latency, not
+breakage.
+
+If you have a route that genuinely must render before organization context exists, pass
+`waitForOrganization={false}` explicitly. Relying on the old default is no longer possible.
+
+**2. Invited members who have not signed up yet are now visibly distinguished.** A previous train
+made them _appear_ in your members list, which fixed wrong counts. It did not make them
+_identifiable_ — the type shipped but the renderer did not, so every member looked equally
+provisioned. `ProvisioningStateBadge` now ships inside `@elevasis/ui` and `OrgMembersList` renders it
+beside the existing status badge, in the same cell rather than a new column. A fully-provisioned
+member renders nothing, so nothing about your existing rows changes.
+
+**3. Membership responses carry an explicit `workosMembershipId`, and `membership.id` is the platform
+UUID.** The API used to be inconsistent about which identifier a membership response carried. It is
+now uniform: `id` is always the platform's own UUID, and the WorkOS identifier has its own named
+field. Both forms are accepted on lookup, so a request built either way still resolves.
+
+**`organization.workos_org_id` is unchanged and still carries the WorkOS `org_…` value verbatim.**
+That is the field your project selects organizations on and drives `switchToOrganization` with. It
+was audited specifically because this change was in the same area; nothing about it moved.
+
+**4. Four invitation API routes were removed** — `POST /api/invitations/accept`, and the
+`GET /api/invitations`, `GET /api/invitations/:id`, `GET /api/invitations/summary` trio. All four
+were dead surface with no caller in any project we could find. If you have an out-of-tree script
+calling one, it will now 404.
+
+**5. `@elevasis/sdk` fixes a JSON-safety defect in truncated tool results.** When a long tool result
+was truncated, a cut landing between a key's closing quote and its colon left behind a key with no
+value — `{"alpha":"…","nested"}` — which is not parseable JSON. Your agents read slightly malformed
+JSON rather than crashing, because the parser falls back to the raw string, so the practical impact
+was low. It is fixed regardless. The window was a few characters per key, which is why casual testing
+never surfaced it.
+
+## Applies to
+
+- **Every template-family project**, for items 1 through 3. All are consumed through the published
+  packages with no source edits on your side.
+- **Any project whose settings page renders `OrgMembersList`** — that is the published component,
+  so the badge arrives with the `@elevasis/ui` bump.
+- **Every project running agents**, for item 5. The truncation fix lives in the worker runtime that
+  `operations/` bundles, so it reaches you through `@elevasis/sdk`.
+- **Not applicable to your organization model, knowledge nodes, or workflow definitions.** Nothing in
+  this train touches authored content.
+
+## Required actions
+
+1. **Take the `@elevasis/core`, `@elevasis/ui`, and `@elevasis/sdk` baseline bumps** this train
+   propagates, then reinstall in `core/`, `ui/`, and `operations/`.
+
+2. **Clear the Vite cache and restart your dev server.** A stale `.vite` cache serves the old bundle
+   while every gate reports green — that is the specific way this failure hides:
+
+   ```bash
+   rm -rf ui/node_modules/.vite
+   pnpm -C ui dev
+   ```
+
+3. **Redeploy `operations/` to pick up the truncation fix.** The baseline bump changes what your
+   next bundle contains; it does not change what is already deployed:
+
+   ```bash
+   pnpm -C operations exec elevasis-sdk deploy
+   ```
+
+4. **Check any route that must render before organization context exists.** If you have one, add
+   `waitForOrganization={false}` explicitly. If you are unsure whether you have one, the audit result
+   above says you almost certainly do not — every affected route in every project is
+   organization-scoped already.
+
+## Verification
+
+- **Sign in and land on your home route.** This is the check that matters most, because the guard
+  default changed on the route that greets you. Confirm it renders, and that navigating to
+  `settings/appearance` and `settings/account` still works — those are the two user-scoped pages that
+  now wait for organization context they do not strictly need.
+- **Open your settings members page.** Any member you have invited who has not completed signup
+  should now carry a visible badge; fully-provisioned members should look exactly as before.
+- **Read the installed bundle, not the version number.** A bumped pin and a green sync report are
+  claims about intent; the installed file is the only ground truth:
+
+  ```bash
+  grep -rl "ProvisioningStateBadge" ui/node_modules/@elevasis/ui/dist/components/
+  grep -c "innermostIsObject" operations/node_modules/@elevasis/sdk/dist/worker/index.js
+  ```
+
+  No match on the first, or `0` on the second, means the install did not land regardless of what
+  `package.json` says.
+
+## Not handled by /git-sync
+
+- **The Vite cache clear and dev-server restart.** `/git-sync` propagates and commits the dependency
+  baseline. Your running dev server keeps serving the previously cached bundle until you do step 2
+  yourself, and it will look like the sync did nothing.
+- **The `operations/` redeploy.** Bumping the `@elevasis/sdk` pin changes what your next bundle
+  contains. Your currently deployed workers keep running the old bundle until you deploy.
+- **Adding `waitForOrganization={false}` to a route that needs it.** Nothing can detect that
+  automatically — only you know whether a route is legitimately pre-organization.
+- **Replacing calls to the four removed invitation routes.** If an out-of-tree script calls one, the
+  sync cannot see it.

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