@elevasis/sdk 1.44.3 → 1.46.0

package/reference/claude-config/sync-notes/2026-08-03-agent-prose-escape-normalization.md

@@ -1,88 +0,0 @@
-# Agent prose is repaired before it is stored
-
-## Why this note exists
-
-**Your agents have been writing the two characters `\n` into their replies where a line break
-belongs, and `\"` where a quotation mark belongs.** The operator reads `\n\n` in the middle of a
-sentence, and the stored transcript keeps those characters forever.
-
-Measured on 2026-08-03 across four 14-turn production sessions on a live tenant agent — 56 assistant
-replies:
-
-| Surface     | Rows | Rows affected | Literal `\n` | Literal `\"` |
-| ----------- | ---- | ------------- | ------------ | ------------ |
-| `message`   | 56   | 28            | 111          | 146          |
-| `reasoning` | 56   | 1             | 4            | 0            |
-
-Half the replies were affected. This is a different defect from the em-dash corruption in
-`2026-07-28-agent-reply-is-its-own-field.md`, and that fix still holds — em-dashes were clean across
-all 56 replies here. This one is on the field that fix created.
-
-**The model is choosing the wrong characters, not the wrong encoding.** Three replies carried one
-paragraph break written as real newlines and another written as the two characters, inside the
-_same string_. No serialization layer produces that — a layer that escapes, escapes everything. So
-there is nothing to wait for on the provider side: the output is valid JSON, it satisfies the
-response schema, and no parser can tell the difference.
-
-**It also feeds back.** Assistant text is replayed verbatim into the next turn as trusted context,
-so a damaged reply becomes evidence to the model of how this agent writes.
-
-The runtime now repairs it deterministically at the single point where model output is validated —
-upstream of persist, stream, render, and replay. `\n`, `\r\n`, `\t`, and `\"` are converted to the
-characters they denote in `message`, in `reasoning`, and in session-memory values.
-
-## Applies to
-
-- **Every agent, not only session-capable ones.** `reasoning` and `memoryOps` are normalized on all
-  agents; `message` on the ones that have it.
-- **Session memory especially.** A stored memory value is re-sent on every iteration of every
-  later turn and never ages out, so one literal escape stored there is one the model re-reads for
-  the life of the session. This surface had never been measured before this train.
-- **No agent definition changes are required.** You do not edit your agents. The repair lives in the
-  runtime your bundle carries.
-
-## Two behaviors worth knowing
-
-1. **The normalizer is not markdown-aware.** A fenced code block or inline span containing a literal
-   `\n` **is** converted. This was a deliberate trade: a reply whose line breaks are all literal has
-   no line structure for a fence to start on, so the replies most in need of repair are exactly the
-   ones a fence scan would fail to parse. If you run an agent that discusses escape sequences or
-   regexes in its user-facing prose, this is the case to check.
-2. **A doubled backslash is left alone**, and JSON-shaped memory values are skipped entirely — so a
-   stored JSON blob keeps its internal escaping and still parses.
-
-## Required actions
-
-1. **Take the `@elevasis/sdk` baseline bump** this train propagates, then reinstall in `operations/`
-   so the new worker bundle is present.
-2. **Redeploy your operations bundle.** This is the step that closes the defect. The agent loop is
-   inlined into your deployed bundle, so an existing deployment keeps emitting damaged prose until
-   it is redeployed:
-
-   ```bash
-   pnpm -C operations exec elevasis-sdk deploy --prod
-   ```
-
-   A platform-side deploy does not fix this for you, and neither does the reinstall on its own.
-
-3. **Do not treat existing transcripts as clean.** No backfill is performed. Replies and memory
-   snapshots written before your redeploy keep the literal escapes they already have. Memory
-   snapshots in particular are live agent state, and rewriting them mid-session was judged riskier
-   than the damage.
-
-## Verification
-
-- Run a multi-turn session and ask for a reply with paragraph structure — a short summary in two or
-  three paragraphs is enough. Read the reply: the signature failure is a visible `\n\n` between
-  sentences, or a quotation mark rendered as `\"`.
-- **Check a reply containing quoted speech.** Quote escapes were the larger surface (146 of 257
-  measured occurrences), and one measured reply carried six of them with no newline escapes at all —
-  so a reply can be damaged purely on quotes and look fine structurally.
-- If your agent declares `memoryPreferences`, run enough turns for it to write session memory, then
-  confirm a stored value comes back with real line breaks rather than literal ones.
-
-## Not handled by /git-sync
-
-- **The redeploy.** `/git-sync` commits and pushes the propagated dependency baseline. Your deployed
-  agents keep producing damaged prose until you run action 2 above.
-- **Repairing existing transcripts or memory snapshots.** No backfill is performed, by decision.

package/reference/claude-config/sync-notes/2026-08-03-cli-gateway-errors-and-request-timeout.md

@@ -1,120 +0,0 @@
-# Your CLI now explains a 502 instead of just reporting one, and no request hangs forever
-
-## Why this note exists
-
-This train publishes one package — `@elevasis/sdk` — and every change in it is in the CLI you type
-commands into. Nothing about your workflows, organization model, or UI moves. But the CLI's failure
-messages change, and one of them changes in a way that is meant to stop you doing something harmful.
-
-**1. A gateway failure now tells you the work may still be running, and how to check.** Until now
-every non-2xx response produced the same shape: `API request failed (502)`. That message is
-technically accurate and practically dangerous, because the most natural reaction to it is to run the
-command again.
-
-A 502, 503, or 504 does not come from the platform API. It comes from a hop in front of it that ended
-your connection while the API was still working. The request you sent may have completed in full. We
-found this the hard way: a session turn returned 502 to the CLI after 300 seconds, and a later
-database query showed the turn had **completed successfully server-side in 319.8 seconds** with a
-model reply written and no error of any kind. The only thing that failed was the connection carrying
-the answer back. It was turn 14 of a 14-turn run — re-running blind would have executed that turn a
-second time.
-
-The new message says the proxy ended the connection, that this is not the API rejecting your request,
-that the work may still be running, and which command to use to look for a result before re-running.
-
-**2. Every CLI request is now bounded by a timeout, defaulting to 2 hours.** Before, the CLI used a
-bare `fetch()` with no signal, so a connection that stalled would sit there indefinitely with no
-output. The limit is deliberately set high — it matches the server's own socket budget on long routes.
-The goal is to bound an indefinite hang, not to police how long your work may take. Anything shorter
-would make the CLI give up on executions the API is still legitimately serving, turning a working long
-run into a reported failure. Override it with `ELEVASIS_CLI_TIMEOUT_MS` if you have a reason to.
-
-**3. "Timed out" and "never reached the API" are now different messages.** A bare `fetch()` rejection
-carries no status, so a dead port, a wrong API URL, and a stalled connection were indistinguishable.
-They now read differently.
-
-**4. The friendly authentication message now applies to every verb.** A 401 on `GET` printed a clear
-"check your platform key" message; a 401 on `POST`, `PATCH`, or `DELETE` printed the raw response
-body. All four now share the same message.
-
-**5. Three dead exports were removed from the agent memory surface.** `MEMORY_DOMAINS.ACTION_OWNED`
-was an empty array, `isActionOwnedKey` returned `false` for every input, and the `ActionOwnedKey` type
-resolved to `never`. They are gone. The live half of that layer is unchanged and still enforced: an
-agent still cannot write to a tool-owned memory key. If your project imports any of the three removed
-names, it was importing something that could never do anything — but the import will now fail, so it
-is worth a grep.
-
-## Applies to
-
-- **Every project that uses the `elevasis-sdk` CLI**, which is every template-family project. Items 1
-  through 4 arrive with the baseline bump and need no source edit from you.
-- **Any script or CI job that parses CLI stderr.** The gateway, timeout, and transport messages are
-  new text. If something greps for `API request failed`, check it.
-- **Any project importing `ACTION_OWNED`, `isActionOwnedKey`, or `ActionOwnedKey`** from the SDK, for
-  item 5. We found no such import in any template-family project, but only you can see out-of-tree
-  code.
-- **Not applicable to your organization model, knowledge nodes, workflows, or UI.** Nothing in this
-  train touches authored content or any rendered surface.
-
-## Required actions
-
-1. **Take the `@elevasis/sdk` baseline bump** this train propagates, then reinstall in `operations/`:
-
-   ```bash
-   pnpm -C operations install
-   ```
-
-2. **Grep for the three removed memory exports** before you deploy. This is the only change in the
-   train that can break a build, and it is cheap to rule out:
-
-   ```bash
-   grep -rn "ACTION_OWNED\|isActionOwnedKey\|ActionOwnedKey" operations/src core/config
-   ```
-
-   No output means item 5 does not affect you.
-
-3. **Redeploy `operations/`.** 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 script that matches on CLI error text.** If you have automation that branches on
-   `API request failed`, it will no longer match a gateway failure.
-
-## Verification
-
-- **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 -c "GATEWAY_STATUSES" operations/node_modules/@elevasis/sdk/dist/cli.cjs
-  grep -c "ACTION_OWNED" operations/node_modules/@elevasis/sdk/dist/worker/index.js
-  ```
-
-  The first must be non-zero and the second must be `0`. Either result the other way means the
-  install did not land, regardless of what `package.json` says.
-
-- **Provoke a transport failure and read the message.** The cheapest honest check that the new
-  branches are live, because it needs no broken server:
-
-  ```bash
-  ELEVASIS_API_URL=http://localhost:9 pnpm -C operations exec elevasis-sdk list
-  ```
-
-  You should get a message naming the endpoint and saying the request never reached the API — not a
-  bare `fetch failed`.
-
-- **Confirm the timeout is configurable.** Setting `ELEVASIS_CLI_TIMEOUT_MS=1` on any command should
-  produce a timeout message that quotes the limit back to you.
-
-## Not handled by /git-sync
-
-- **The `operations/` reinstall.** `/git-sync` propagates and commits the dependency baseline. The
-  `node_modules` copy your CLI actually executes is not updated until you run `pnpm install` yourself,
-  and the CLI will keep printing the old messages until you do.
-- **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.
-- **The grep for the removed memory exports.** Nothing can detect an out-of-tree import for you.
-- **Updating scripts that match on CLI error text.** The sync cannot see your automation.

package/reference/claude-config/sync-notes/README.md

@@ -1,43 +0,0 @@
-# Sync Notes
-
-Template-owned downstream migration guidance lives in this directory.
-
-## File Contract
-
-- Operative note files must be named `YYYY-MM-DD-<slug>.md`
-- `README.md` explains the contract and is ignored by `/git-sync`
-- Notes are append-only. Add a new dated file for each downstream-affecting release train instead of rewriting an older note
-
-## When A Note Is Mandatory
-
-Add a new operative note whenever a train affects derived projects beyond a normal pull, install, and baseline verify. Common triggers:
-
-- template dependency-baseline changes
-- scaffold or sync-contract changes
-- rename or migration work
-- verifier or behavior changes that downstream maintainers need to understand
-- any release train that will ask maintainers to do manual follow-up after pulling
-
-## Required Sections
-
-Every operative note must include these exact headings:
-
-## Why this note exists
-
-Explain what changed and why downstream maintainers are seeing this note.
-
-## Applies to
-
-State which projects, app modes, or versions need the follow-up.
-
-## Required actions
-
-List the manual work maintainers need to do after `/git-sync`.
-
-## Verification
-
-List the commands or flows that confirm the migration landed correctly.
-
-## Not handled by /git-sync
-
-Call out what remains manual so maintainers do not assume the pull/install/verify flow reconciled everything.

package/reference/sdk/framework/interaction-guidance.mdx

@@ -1,182 +0,0 @@
----
-title: "Interaction Guidance"
-description: "Full dimensional adaptation rules per skill axis -- platform navigation, API integration, automation concepts, domain expertise -- with growth tracking protocol"
-loadWhen: "Unsure how to adapt for a skill combination"
----
-
-This reference defines how to adapt every interaction based on the dimensions in `.claude/memory/profile/skills.md`. Read it when the compact directive in CLAUDE.md is not enough to decide how to handle an unusual skill combination.
-
----
-
-## Skill Dimensions
-
-The user profile stores four independent skill dimensions. Each dimension has its own adaptation rules. Do not collapse them into a single beginner/intermediate/advanced rating.
-
-### Platform Navigation (none / oriented / comfortable)
-
-**none** -- Never used the Command Center. Does not know where pages are.
-
-- Walk through each page step by step before directing the user there
-- Provide exact navigation paths (e.g., "Open the Command Center, then click Execution Runner in the left sidebar")
-- Explain what each page does before asking them to use it
-- Do not assume they can find a page by name alone
-
-**oriented** -- Has explored the Command Center, knows the main sections.
-
-- Reference pages by name (Execution Runner, Command Queue, Task Scheduler)
-- Briefly remind the user what a page does on first mention in a session
-- Trust them to navigate once you name the destination
-
-**comfortable** -- Regularly uses the Command Center without guidance.
-
-- Reference pages by name only, no reminders needed
-- Focus on advanced filtering, schedule types, and log detail navigation
-- Trust them to explore and navigate independently
-
----
-
-### API and Integration (none / basic / proficient)
-
-**none** -- Has not called an API directly. Uses tools with built-in integrations.
-
-- Explain what credentials are and why they exist before any integration code
-- Walk through credential creation in the platform command center step by step
-- Explain what "calling an API" means in plain English
-- Explain why `.env` exists and what `ELEVASIS_PLATFORM_KEY` is for
-- Do not assume they understand HTTP methods, JSON, or authentication headers
-
-**basic** -- Has used APIs with documentation or built simple integrations.
-
-- Show `platform.call()` patterns with brief notes on credential names
-- Reference the platform credential system for setup without full walkthrough
-- Explain SDK-specific credential patterns (how the platform injects secrets server-side)
-
-**proficient** -- Has built production integrations, understands REST and auth patterns.
-
-- Just the code and credential name
-- Trust them to set up credentials in the command center without guidance
-- Focus on SDK-specific behavior (timeout, error types, server-side injection)
-
----
-
-### Automation Concepts (none / low-code / custom)
-
-**none** -- Has not used automation tools. Thinks in manual processes.
-
-- Use analogies before any technical explanation (see Analogies section)
-- Explain the execution model early: "Your code runs on Elevasis servers, not your computer"
-- Define Workflow, Step, Trigger, Schema, Credential on first use
-- Explain why automation is valuable for their specific use case before building anything
-- Explain deploy: "After deploy, your workflow is live and can be triggered"
-
-**low-code** -- Has used Zapier, Make, or similar tools.
-
-- Map Elevasis concepts to tools they know: "Steps are like Zapier actions. The workflow is the Zap."
-- Focus on what is different: code is more flexible but requires TypeScript
-- Explain schema validation: "Zapier has field mapping; Elevasis has schemas that validate the shape of data"
-
-**custom** -- Has written custom automation scripts or integrations.
-
-- Skip analogies
-- Focus on the SDK execution model: worker threads, postMessage, ephemeral processes
-- Explain the credential security model (server-side injection, no env vars in workers)
-- Discuss error handling patterns and retry behavior
-
----
-
-### Domain Expertise
-
-Domain expertise is not a code skill. It is the user's depth of knowledge in their industry or business function (sales, finance, operations, marketing, etc.).
-
-When domain expertise is high:
-
-- Ask for business process descriptions before designing schemas
-- Let them drive the "what" (business logic); you handle the "how" (implementation)
-- Translate their process description into workflow steps, schemas, and tool choices
-- Validate your understanding: "So the workflow should: receive a new lead from the CRM, score it based on these criteria, and send a Slack alert if the score is above 80?"
-- Trust their judgment on what the workflow should do; never second-guess business logic
-
-When domain expertise is low:
-
-- Ask clarifying questions about the business process before designing anything
-- Do not assume what "a lead" or "a deal" or "an invoice" means in their context
-- Confirm edge cases explicitly: "What should happen if the lead has no email address?"
-
----
-
-## Analogies for Non-Technical Users
-
-Use these when programming level is none or minimal, or when automation level is none.
-
-| Concept       | Analogy                                                                                                     |
-| ------------- | ----------------------------------------------------------------------------------------------------------- |
-| Workflow      | A recipe: ingredients go in (input), steps are instructions, finished dish comes out (output)               |
-| Step          | One instruction in a recipe: "add salt," "stir for 2 minutes"                                               |
-| Schema        | A form template: it defines what fields exist and what type of data each field accepts                      |
-| Deployment    | Publishing: like publishing a document so others can access it                                              |
-| Execution     | One run: like baking the recipe once                                                                        |
-| Platform tool | A kitchen appliance: you use the mixer (tool) without knowing how it works inside                           |
-| Credential    | A key: you give Elevasis the key to your Gmail account; it unlocks the door when needed                     |
-| Assembly line | Raw material goes in one end (input), each station does one job (step), finished product comes out (output) |
-
-Choose the analogy that fits the user's domain. A sales operations person will relate more to "a form template" than a developer would.
-
----
-
-## Growth Tracking Protocol
-
-### Observations
-
-During each session, note behaviors that reveal skill level changes. Examples:
-
-- User wrote a handler without asking for help
-- User suggested using StepType.CONDITIONAL without prompting
-- User asked a question that shows they now understand the execution model
-- User navigated to the correct Command Center page without being directed
-- User filtered Execution Logs by resource independently to diagnose a failure
-- User created a Task Scheduler entry unassisted
-
-### Promotion Rules
-
-Do not automatically update the skill profile for every observation. Update when:
-
-- The user independently performs a task they previously needed explicit help with
-- The behavior is consistent across at least two instances (not a one-off)
-- The observation demonstrates understanding, not just copying a pattern
-
-### Update Format
-
-When updating `.claude/memory/profile/skills.md` Growth Log:
-
-```
-| Date | Observation | Dimension | Change |
-| 2026-03-01 | Navigated to Execution Logs and filtered by resource without direction | platformNavigation | none -> oriented |
-```
-
-Also update the dimension's Level and Since fields in the Dimensions table.
-
-### Celebration
-
-When growth is observed, acknowledge it briefly:
-
-- "You found that on your own -- looks like you've got the Command Center navigation down."
-- "Good catch on the optional field -- that is exactly the kind of thing that trips people up."
-
-Keep it natural. One sentence is enough. Do not over-celebrate.
-
----
-
-## When This Reference is Needed
-
-Load this file when:
-
-- Starting `/meta init` to understand how to phrase the competency assessment questions
-- The user's skill combination is unusual and the compact CLAUDE.md directive is not enough to decide how to respond
-- Reassessing skill levels after several sessions
-- Writing the initial profile during onboarding
-
-For routine sessions, the compact directive in CLAUDE.md plus the user's stored `skills.md` is sufficient.
-
----
-
-**Last Updated:** 2026-02-26