v6.0.0-beta.1

.claude/logs/agent-2-planning-v6.0.0-beta.1-approval-engine-agent-tooling.md

@@ -0,0 +1,102 @@
+# Release Update Plan for v6.0.0-beta.1 — Approval Engine & Agent Tooling (23 Jun 2026)
+
+> Scope note: This is the SECOND release note appended to the existing `<Update label="6.0.0-beta.1">` block. The base modular-SDK plan is in `agent-2-planning-v6.0.0-beta.1.md` — do NOT touch that work. This log covers ONLY the Approval Engine + Agent Tooling items.
+
+## Overview
+- Release Type: Minor + one Breaking Change (within an existing beta version).
+- Key Changes: Approval Engine unified `edges[]` contract (removes `onReject`/`loops[]`); read-only `compiled` block on DefinitionView; `waitAll`/`cancelOnQuorum` groups as edge sources; node cosmetic `name`/`description`; three new agent capabilities (`rest-api` context strategy, `mcp-tools` execution strategy, `docs-code-comparison` built-in agent); custom-agent config validation changes.
+- Breaking Changes: YES — Approval Engine `edges[]` migration. Upgrade guide currently says "None — fully backward compatible," which is now WRONG and is the highest-priority gap.
+
+## Areas Requiring Updates
+
+### 1. Data Models
+- Not applicable. Approval Engine + agent config schemas live in REST reference and conceptual pages, not `data-models.mdx` (SDK frontend types). No new SDK-facing types. SKIP.
+
+### 2. API Methods
+- Not applicable. No new SDK hooks/facade methods. All surface is REST + conceptual. SKIP.
+
+### 3. Documentation / REST Reference
+
+**3a. Upgrade Guide — HIGHEST PRIORITY (breaking change)**
+- File: `/Users/yoenzhang/Downloads/docs/release-notes/version-6/upgrade-guide.mdx`
+- Changes: Replace "## Breaking Changes → None" (line 11-13) with an Approval Engine entry: the four-row `onReject`/`loops[]` → `edges[]` migration mapping (from raw input lines 14-22), the new `EdgeSchema` fields (`from`/`to`/`on`/`when`/`loop`), and the new `INVALID_ARGUMENT` error keys (raw input lines 31-41). Migration table belongs HERE, never in the changelog.
+- Priority: High.
+
+**3b. Approval Engine REST — Create Definition**
+- File: `/Users/yoenzhang/Downloads/docs/api-reference/rest-apis/v2/approval-engine/definitions/create-definition.mdx`
+- Changes: Rewrite `edges` ParamField to the unified EdgeSchema (`from`/`to`/`on`/`when`/`loop`); REMOVE the `loops` ParamField (lines 62-64); add node `name`/`description` to node config; note group-as-edge-source (`waitAll`/`cancelOnQuorum`); update edge example + success response to show `compiled` block. Edge `when` is now valid only on `on:"custom"`.
+- Priority: High.
+
+**3c. Approval Engine REST — Update Definition**
+- File: `/Users/yoenzhang/Downloads/docs/api-reference/rest-apis/v2/approval-engine/definitions/update-definition.mdx`
+- Changes: Mirror 3b edge/loops/node changes; remove `onReject`/`loops[]` references.
+- Priority: High.
+
+**3d. Approval Engine REST — Get Definition**
+- File: `/Users/yoenzhang/Downloads/docs/api-reference/rest-apis/v2/approval-engine/definitions/get-definition.mdx`
+- Changes: Document read-only `compiled` block (`compiled.forwardEdges` + `compiled.loops`, schema from raw input lines 51-67) in the response; note authored `edges` echo `sourceEdges` byte-for-byte; remove `onReject`/`loops[]` echo references.
+- Priority: High.
+
+**3e. Approval Engine REST — List Definitions**
+- File: `/Users/yoenzhang/Downloads/docs/api-reference/rest-apis/v2/approval-engine/definitions/list-definitions.mdx`
+- Changes: Note each row carries the `compiled` block; remove `onReject`/`loops[]` references.
+- Priority: Medium.
+
+**3f. Approval Engine Conceptual — Customize Behavior (largest revision, 44KB)**
+- File: `/Users/yoenzhang/Downloads/docs/ai/approval-engine/customize-behavior.mdx`
+- Changes: Remove/rewrite the "Per-human-node `onReject` shorthand" section (lines 59-131), the `loops[]` region model, and "When to use a loop vs. the `onReject` shorthand" (line 259). Replace with unified `edges[]`: reject path = outgoing `on:"reject"` edge; loop-back = `on:"reject"` edge with `loop`; exhausted = sibling `on:"exhausted"` edge. Add group-as-edge-source semantics (waitAll unanimity, cancelOnQuorum quorum) and node `name`/`description`. Add the new `APPROVAL_EDGE_*` error keys.
+- Priority: High.
+
+**3g. Approval Engine Conceptual — Setup**
+- File: `/Users/yoenzhang/Downloads/docs/ai/approval-engine/setup.mdx`
+- Changes: Rewrite `onReject.routeToNodeId` walkthrough (lines 62-105), the "Rejection handling: shorthand vs. loops" guidance (line 323), and the "Human node missing a reject path" troubleshooting (line 365) to the `edges[]` model. Fix anchor links pointing to removed customize-behavior sections.
+- Priority: High.
+
+**3h. Approval Engine Conceptual — Overview**
+- File: `/Users/yoenzhang/Downloads/docs/ai/approval-engine/overview.mdx`
+- Changes: Verify no `onReject`/`loops[]` mentions remain; add `compiled` block and group-as-edge-source to feature list if applicable. Agent-3: grep first, edit only if hits.
+- Priority: Low.
+
+### 4a. UI Customization — Wireframes
+- Not applicable. Backend/REST release, no wireframes. SKIP.
+
+### 4b. UI Customization — Primitives
+- Not applicable. No primitive components. SKIP.
+
+### 5. Upgrade Guide (breaking changes)
+- Covered in 3a. Breaking changes go ONLY in upgrade-guide.mdx, never the changelog.
+
+## NO DOC TARGET — HUMAN DECISION REQUIRED (flag for Agent-3)
+
+The three new agent capabilities and the custom-agent config validation changes have NO existing public doc surface. Existing agent pages: `ai/agent-comments.mdx` (agents leaving comments, unrelated) and `api-reference/rest-apis/v2/agents/` (only `list-agent-executions.mdx`). Agent-1 deliberately omitted "Learn more" links for all 7 agent items.
+
+Items with no home:
+- `rest-api` context-gathering strategy (raw input lines 83-97: `strategyOptions["rest-api"]`, `RestApiEndpoint` shape, SSRF guard, `{{restApiData}}`).
+- `mcp-tools` execution strategy (raw input lines 99-110: `execution.mcpServers[]` shape, allowlists, max-turn cap).
+- `docs-code-comparison` built-in agent (raw input lines 112-115).
+- Custom-agent config validation: deep-merge partial updates; reject server-managed fields (`managedBy`, `metadata.*`) with per-key 400; `instructions` required for `ai`/`service+ai`/`stagehand-agent`; `listVersions` fail-closed secret redaction.
+
+Recommendation: warrants ONE new custom-agent configuration reference page (execution strategies + context-gathering strategies + built-in agents + config validation), e.g. `ai/agents/configuration.mdx` or `api-reference/rest-apis/v2/agents/`. DECISION DEFERRED to human — do NOT invent a page or fabricate URL paths this pass. If approved, Agent-3 also adds nav entries to `docs.json` (agents section near line 311 / 827).
+
+## DO NOT DOCUMENT (confirmed internal refactors)
+ApiKeySecretCipher extraction; ProviderApiKeyService extraction; CryptoUtil/CRDT barrel-import migration; compileGraph-vs-linter validation split; ILlmProvider.askAIWithTools adapter internals; McpClientService internal plumbing. Email-digest determinism bug fix = changelog only, no reference doc.
+
+## Implementation Sequence
+1. Upgrade guide breaking-change entry + migration table (High; blocks correctness of changelog link).
+2. Approval Engine REST: create + update (edges/loops/node) (High).
+3. Approval Engine REST: get + list (`compiled` block) (High/Medium).
+4. Conceptual: customize-behavior rewrite, then setup (depends on customize-behavior anchors) (High).
+5. Conceptual: overview grep-and-fix (Low).
+6. Agent tooling: PAUSE — await human decision on new page before any agent-config docs.
+
+## Quality Checklist
+- [ ] Breaking change moved to upgrade-guide.mdx ONLY (not changelog).
+- [ ] Migration table (onReject/loops[] → edges[]) + new error keys in upgrade guide.
+- [ ] All `onReject`/`loops[]`/`loopBack` references removed from REST + conceptual pages.
+- [ ] `compiled` block documented on get/list/create responses.
+- [ ] Group-as-edge-source (waitAll/cancelOnQuorum) + node name/description documented.
+- [ ] No broken anchors after customize-behavior section removals (setup.mdx links).
+- [ ] Code examples keep `React/Next.js` first, `Other Frameworks` second where tabs apply (REST pages are framework-agnostic JSON).
+- [ ] Agent-tooling new-page decision surfaced to human; no invented URLs.
+- [ ] Internal refactors NOT documented.
+- [ ] Log written to `.claude/logs/agent-2-planning-v6.0.0-beta.1-approval-engine-agent-tooling.md`.

.claude/logs/agent-2-planning-v6.0.0-beta.1.md

@@ -0,0 +1,88 @@
+# Release Update Plan for v6.0.0-beta.1
+
+## Overview
+- Release Type: Major (modular SDK; lazy feature chunks)
+- Key Changes: New `featureAllowList` modular semantics; 19 `preload*()` facade methods; 16 `getXElement()` accessors now return non-blocking lazy facades; new `Features.CRDT='crdt'` enum value; Transcription folded into recorder chunk; 2 bug fixes.
+- Breaking Changes: No hard API break — existing code compiles/runs as-is (lazy facades cast to public element types; `featureAllowList` default = preload all = pre-modular behavior). Behavior change only. Upgrade-guide narrative already authored by Agent-1.
+- Scope: Pure SDK infrastructure. No new UI components, primitives, or wireframes.
+
+## Areas Requiring Updates
+
+### 1. Data Models — `api-reference/sdk/models/data-models.mdx`
+File: `/Users/yoenzhang/Downloads/docs/api-reference/sdk/models/data-models.mdx`
+
+- UPDATE `#### Config` → `featureAllowList` row (line 4584). Do NOT add a duplicate row. Rewrite description to cover modular behavior: default `undefined` ⇒ preloads ALL lazy chunks (pre-modular behavior); passing it preloads ONLY the listed feature chunks (others deferred until `preloadX()`/`getXElement()`); allow-list auto-extends when an omitted feature's accessor/preload is called.
+- ADD to `#### Features` enum (table at lines 4594–4607): one new row `CRDT | 'crdt' | No | CRDT feature (lazy chunk velt-crdt.js)` in correct alphabetical position (between `AUDIO_HUDDLE` and `COMMENT`, i.e. after `COMMENT`? — alphabetical by Property: CRDT sorts before COMMENT? No: "CRDT" < "COMMENT"? compare char 2: R vs O → O<R, so COMMENT precedes CRDT). Insert CRDT AFTER `COMMENT`, before `CURSOR`. Priority: High.
+- FeatureType/Features decision: `FeatureType` has NO standalone `####` heading in data-models.mdx (only referenced by the `featureAllowList` row and `disableFeatures()` params). `#### Features` enum IS the canonical doc for these keys. Recommendation: document `CRDT` in `#### Features`; do NOT create a new `#### FeatureType` heading.
+- LazyXElement classes: DO NOT document (internal — "no change to your code"; consumers use public element types behind a cast). Confirmed stance.
+- Priority: High.
+
+### 2. API Methods — `api-reference/sdk/api/api-methods.mdx`
+File: `/Users/yoenzhang/Downloads/docs/api-reference/sdk/api/api-methods.mdx`
+
+Structure found (relevant regions):
+- `# Core` → `### Client` (line 3046): `initConfig()` 3047, `getVeltInitState()` 3054, `get Velt Client` 3060.
+- `### Feature Utilities` (line 3583): getXElement accessors — getPresenceElement 3584, getCursorElement 3591, getCommentElement 3598, getSelectionElement 3605, getRecorderElement 3612, getRewriterElement 3626, getLiveStateSyncElement 3633, getArrowElement 3640. (getContactElement, getSuggestionElement also here.)
+- getCrdtElement 3308 (under CRDT `### Element Access`); getActivityElement 1857 (under Activity `### Element Access`). Accessors are NOT all colocated.
+- `### Feature Gating` (line 3655): isUserAllowed$ 3656, disableFeatures 3663 (`features: Array<FeatureType>`), isPlanExpired$ 3670.
+- Method entry format: `#### name()` + 1-line description + `- Params:` + `- Returns:` + `- React Hook:` (+ optional `- [Full Documentation →]`).
+
+Changes:
+- ADD a new subsection `### Modular SDK / Chunk Preloading` immediately AFTER `### Feature Gating` (insert after line 3675, before `### Localization` at 3678). Rationale: feature-gating semantics live here (disableFeatures/featureAllowList); keeps modular material in one discoverable block. Contents:
+  - Intro note: featureAllowList modular behavior (default undefined ⇒ preload all chunks; passing it preloads only listed chunks; inert-tag/auto-upgrade — tags placed before chunk loads render as inert HTMLUnknownElement and silently no-op until the chunk lands then custom-elements lifecycle upgrades them in place; allow-list AUTO-EXTENSION via ensureFeatureEnabled when an omitted feature's accessor/preload is called; tag-only features note: userInvite/userRequest/videoPlayer have no getXElement accessor → must use featureAllowList or preloadX()). Link featureAllowList to `/api-reference/sdk/models/data-models#config`.
+  - The 19 `preload*()` entries, each: `#### preload<Feature>()` + "Loads the <feature> lazy chunk and registers its custom elements on demand." + `- Params: void` + `- Returns: Promise<void>` + `- React Hook: n/a`. Note idempotent + non-throwing (logs on failure, resolves) once in the intro, not per-entry, to avoid 19× repetition. The 19: preloadComment, preloadCursor, preloadPresence, preloadHuddle, preloadRecorder, preloadNotification, preloadReaction, preloadArrow, preloadTag, preloadRewriter, preloadSelection, preloadArea, preloadActivity, preloadViews, preloadUserInvite, preloadUserRequest, preloadVideoPlayer, preloadCrdt, preloadLiveStateSync.
+  - Priority: High.
+- ADD lazy-facade behavior note to the `### Feature Utilities` accessor section (short addition, NOT a per-accessor rewrite — return types/method surfaces UNCHANGED). Place one explanatory note at the top of `### Feature Utilities` (after line 3583): getXElement() now returns a non-blocking lazy facade (cast to the real element type, so existing code is unaffected); void methods are queued and flushed once the chunk resolves; promise methods await chunk-load then delegate with original args; observable/on(...) methods return a per-call ReplaySubject(1)-backed proxy stream that bridges once the chunk loads; each accessor also calls ensureFeatureEnabled(...). Recommendation: short subsection note, not a new top-level section.
+  - Priority: Medium.
+- DO NOT add new `####` headings for getViewsElement/getNotificationElement/getReactionElement/getTagElement/getHuddleElement/getAreaElement — they are named in the release note's accessor list but have no existing entries. FLAG for orchestrator: confirm whether these accessors should be newly documented or are intentionally undocumented (see Open Questions). Do not fabricate.
+
+### 3. Documentation (new feature docs)
+- No new standalone feature doc page required. Modular/preload is an SDK-infrastructure concern documented in api-methods.mdx + data-models.mdx + the existing upgrade-guide. Priority: N/A.
+
+### 4a. UI Customization — Wireframes
+- N/A. No new wireframes. (Pure SDK infrastructure.)
+
+### 4b. UI Customization — Primitives
+- N/A. No new primitive components or props. (Pure SDK infrastructure.)
+
+### 5. Upgrade Guide — `release-notes/version-6/upgrade-guide.mdx`
+File: `/Users/yoenzhang/Downloads/docs/release-notes/version-6/upgrade-guide.mdx`
+- Authored by Agent-1. No new breaking-change content from this planning pass (no hard break; default behavior is backward-compatible). If Agent-1's narrative needs the featureAllowList opt-in modular semantics, that already belongs here — NOT in the changelog. Priority: Low (verify only).
+
+### Bug fixes (items 7, 8)
+- Item 7 (video player ensures recorder chunk load to upgrade subtitle/transcription embeds): changelog-only. No reference-doc edit.
+- Item 8 (`<velt-reaction-pin>` per-annotationId subscription so active-state highlight appears reliably): changelog-only. No reference-doc edit.
+- Recommendation: behavior fixes, no API surface change → no data-models/api-methods edits.
+
+## Implementation Sequence
+1. data-models.mdx: update `featureAllowList` description; add `Features.CRDT` row (after COMMENT). Effort: Low.
+2. api-methods.mdx: add `### Modular SDK / Chunk Preloading` section with intro + 19 preload entries. Effort: Medium.
+3. api-methods.mdx: add lazy-facade behavior note atop `### Feature Utilities`. Effort: Low.
+4. Verify upgrade-guide already carries modular opt-in narrative; no changelog breaking-change leakage. Effort: Low.
+
+## Counts to verify downstream (Agent-6/7)
+- 19 lazy chunks = 19 preload methods. CONSISTENT (preload list = 19; chunk list = 19).
+- 16 getXElement accessors (3 tag-only features have none). CONSISTENT (19 features − 3 tag-only = 16).
+- 3 tag-only features: userInvite, userRequest, videoPlayer. CONSISTENT.
+- 1 new enum value: `Features.CRDT='crdt'`. CONSISTENT (only explicit new enum value).
+
+## Terminology to keep EXACT (Agent-6/7)
+`featureAllowList`, `preloadComment`…`preloadLiveStateSync` (19), `getCrdtElement`, `Features.CRDT`, `ensureFeatureEnabled`, `LazyXElement` (internal — do not surface), chunk filenames `velt-comment.js`/`velt-recorder.js`/`velt-crdt.js`/etc.
+
+## Open Questions for Orchestrator (do NOT auto-resolve)
+- DISCREPANCY: release note's featureAllowList key for Live Selection is `selection` (velt-selection.js), but `#### Features` enum documents `LIVE_SELECTION='liveSelection'`. Do not mass-rename. Confirm canonical key with user.
+- Missing-key audit vs `#### Features` enum. Enum currently contains (12): AREA, ARROW, AUDIO_HUDDLE, COMMENT, CURSOR, HUDDLE, LIVE_STATE_SYNC, PRESENCE, TAG, RECORDER, REWRITER, LIVE_SELECTION. Release-note keys NOT present in enum: `crdt` (adding), `notification`, `reaction`, `activity`, `views`, `userInvite`, `userRequest`, `videoPlayer`. Only `CRDT` is the explicit new enum value in the release note → add ONLY CRDT now; flag the others for the user to confirm before adding (release note's simplified key column ≠ enum naming).
+- getViewsElement/getNotificationElement/getReactionElement/getTagElement/getHuddleElement/getAreaElement named in accessor list but undocumented today — confirm whether to add entries.
+
+## Quality Checklist
+- [x] New type/enum value flagged for data-models.mdx (Features.CRDT)
+- [x] All 19 new preload APIs scoped for api-methods.mdx (grouped section + format)
+- [x] featureAllowList description update planned (no duplicate row)
+- [x] Lazy-facade note planned for Feature Utilities (no per-accessor rewrite)
+- [x] LazyXElement confirmed internal — not documented
+- [x] Wireframes (Agent-4) and Primitives (Agent-5) confirmed N/A
+- [x] Bug fixes (7, 8) = changelog-only
+- [x] Breaking changes → upgrade-guide ONLY, never changelog
+- [x] selection/liveSelection discrepancy + missing-key audit flagged, not auto-resolved
+- [x] Counts confirmed internally consistent (19/16/3/1)
+- [x] Log written to `.claude/logs/agent-2-planning-v6.0.0-beta.1.md`