From 6db64d920c1b589d6a07b1759d28a7d19bf45e8c Mon Sep 17 00:00:00 2001 From: os-zhuang Date: Thu, 11 Jun 2026 20:34:28 +0500 Subject: [PATCH] =?UTF-8?q?docs(adr):=20ADR-0040=20Unified=20Assistant=20?= =?UTF-8?q?=E2=80=94=20the=20end=20user=20never=20picks=20an=20agent?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit agent = assembled runtime configuration + governance unit (model, guardrails, planning, memory, persona, skill composition), selected by SCENARIO via the existing resolution chain (app.defaultAgent → platform default → first active) and configured by BUILDERS; skill = reusable capability fragment. The consumer picker leaves chat UX; custom agents stay a builder feature on the same draft→verify→publish pipeline; the tool-scoping gap (tools are registry-global; skills carry discipline, not access control) is named as the follow-up contract. Motivated by the 2026-06-11 staging incident: the Data Assistant accepted a build-an-app job without the authoring disciplines and narrated its own debugging to a business user. Co-Authored-By: Claude Fable 5 --- ...040-unified-assistant-and-agent-binding.md | 104 ++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 docs/adr/0040-unified-assistant-and-agent-binding.md diff --git a/docs/adr/0040-unified-assistant-and-agent-binding.md b/docs/adr/0040-unified-assistant-and-agent-binding.md new file mode 100644 index 0000000000..dd2782a113 --- /dev/null +++ b/docs/adr/0040-unified-assistant-and-agent-binding.md @@ -0,0 +1,104 @@ +# ADR-0040: Unified Assistant — the end user never picks an agent + +**Status**: Proposed (2026-06-11) +**Deciders**: ObjectStack Protocol Architects +**Builds on**: [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (draft-gated authoring tools the assistant drives), [ADR-0038](./0038-build-verification-loop.md) (the verify-fix-reverify discipline carried by skills), ADR-0037 / [framework#1694](https://github.com/objectstack-ai/framework/pull/1694) (Live Canvas — the surface the unified assistant builds into) +**Consumers**: `@objectstack/spec` (agent/skill types — clarified, not changed), `@objectstack/service-ai` (default agent composition), `../cloud/service-ai-studio` (authoring skills attach to the platform assistant), `../objectui` (chat surfaces drop the agent picker) + +**Premise**: pre-launch, no back-compat debt — specify the target end-state directly. + +**Design center**: **the end user talks to "the assistant of this app" — never to a roster.** Asking a business user to choose between "Data Assistant" and "Metadata Assistant" leaks an internal implementation detail and produces the worst failure mode we shipped: the wrong persona accepts the job, lacks the right discipline, and the user watches it flail. + +--- + +## TL;DR + +**The incident that forces the decision** (staging, 2026-06-11): a user asked the *Data Assistant* — the default chat persona — to "build a library app with a dashboard". Tools are registry-global, so it *could* author metadata; but the authoring **disciplines** live in skills it didn't carry (`solution_design`'s plan-first blueprint, `metadata_authoring`'s "don't narrate failures"). Result: it hand-rolled objects field-by-field, collided with a leftover `book` object, fell into a draft-visibility loop, and narrated its own debugging ("add_field said the field exists, but it doesn't") to a business user. The same prompt to the *Metadata Assistant* builds cleanly — but the user had no way to know that, **and should never have to**. + +**Decision.** + +1. **One platform assistant for people.** The default agent carries *all* platform skills — data exploration *and* metadata authoring (`data_explorer`, `actions_executor`, `metadata_authoring`, `solution_design`) — with a short intent preamble: classify the ask (build/change structure vs. query data) and apply that skill's discipline. The skills system already *is* the per-intent behavior mechanism; routing between sibling agents would re-implement it worse (added latency, misclassification, mid-conversation handoff). +2. **The agent picker leaves consumer UX.** Chat surfaces resolve the assistant; they do not offer a roster. Explicit pinning (`?agent=`, API `agents/:name/chat`) remains for builder/developer surfaces (Studio) and programmatic callers. +3. **`agent` stays in the spec — redefined as the *binding unit*, selected by *scenario*, configured by *builders*.** Multiple agents exist so different surfaces bind different assistants; the runtime resolution chain (`app.defaultAgent` → platform default → first active) makes the choice deterministic without user input. +4. **Custom agents are a builder/admin feature**, bound per app, authored as metadata through the same draft → verify → publish pipeline as everything else. Platform guardrails remain a floor no custom agent can lower. +5. **Honest gap, named**: today tools are registry-global and skills carry *instructions only* — a custom agent can change persona, model, and discipline, but **cannot yet constrain capability**. True capability boundaries need **tool scoping** (below), specified here as the follow-up contract. + +--- + +## Context + +### What an `agent` actually is (and why skills can't replace it) + +The agent record carries everything a *deployed assistant* needs that a skill cannot express: + +| Agent-level | Why it can't live on a skill | +|---|---| +| `model {provider, model, temperature, maxTokens}` | cost/quality tier is per-assistant, not per-capability | +| `guardrails {blockedTopics, maxExecutionTimeSec, maxTokensPerInvocation}` | safety/governance envelope around the whole loop | +| `planning {strategy, maxIterations, allowReplan}` | agentic-loop behavior | +| `memory {shortTerm…}` | conversation window | +| `instructions / role / label` | the persona's voice and identity | +| `skills: [...]` | the composition itself | + +**Agent = assembled runtime configuration + governance unit. Skill = reusable capability fragment (tools list + usage discipline).** Deleting the agent type would orphan the model binding and the governance envelope; deleting user-facing agent *choice* costs nothing. + +### Who selects the agent, if not the user? + +The existing resolution chain (already implemented in `agent-runtime.resolveDefaultAgent`): + +1. **`app.defaultAgent`** — the app the user is in selects its assistant (a builder decision made at configuration time); +2. the **platform default** (`data_chat` — after this ADR, the unified assistant); +3. first active agent (stripped-down deployments). + +The analogy that settles it: *agents are to assistants what views are to lists.* An object may define five views; the end user opening a tab doesn't choose among them — the app's navigation does. Nobody asks "why define multiple views, and which one is used?" — binding answers both. A defined-but-unbound agent is simply dormant (API-reachable, bindable later), exactly like a dashboard no nav entry points at. + +### Surfaces and their selectors + +| Surface | Agent | Selected by | +|---|---|---| +| Console chat / Build-with-AI | unified platform assistant | platform (resolution chain) | +| Any app with `defaultAgent` | that agent | **app builder** | +| Studio | `metadata_assistant` via explicit `?agent=` pin | platform (a developer surface) | +| API / MCP callers | named in the request | the program | +| Eval suite (ADR-0038 L5), flow AI steps | named per case/step | the machine | + +## Decision + +### 1. Unified platform assistant (`service-ai` + cloud) + +- The platform default agent's `skills` become the union: `['data_explorer', 'actions_executor', 'metadata_authoring', 'solution_design']`. The cloud's AI Studio plugin keeps owning the two authoring skills; on deployments without it, the skill references simply don't resolve and the assistant degrades to data-only — same graceful-absence rule the registry already applies. +- Base instructions gain an **intent preamble**: *first decide whether the user wants to build/change structure (use the solution-design / authoring disciplines) or query data (use data exploration); never mix the registers.* Skills already carry their own "use this when…" prose; the preamble only forces the classification step. +- Guardrails take the strictest union of the merged personas (authoring's `blockedTopics`, low temperature for build turns). +- The ADR-0038 L5 golden-prompt suite is the regression net for unification: build prompts must still produce clean verified builds, data prompts must still answer — both against the *same* assistant. + +### 2. Consumer surfaces drop the picker (objectui) + +- The chat page resolves the assistant and shows its label — no roster dropdown. The picker renders only when an explicit `?agent=` pin is present (builder/developer flows) or in a future admin surface. +- Floating chat already followed app binding; unchanged. + +### 3. Custom agents — builder feature, same pipeline + +- Builders/admins may define agents (persona, model tier, instructions, skill list) as `type:'agent'` metadata and bind them via `app.defaultAgent`. Definition rides ADR-0033 (draft → publish) and ADR-0038 (verifiable); no parallel lifecycle. +- Platform guardrails are a **floor**: deployment-level limits (blocked topics, token/time ceilings) apply regardless of what a tenant agent declares. + +### 4. The tool-scoping gap (follow-up contract, named honestly) + +Today `chatWithTools` offers the **whole tool registry** to every agent; skills contribute instructions, not access control. Consequences to fix in a follow-up: + +- An agent's effective tool set should be **derivable from its skills** (`skill.tools` as an allowlist) plus an explicit `agent.tools` override — enforced at the runtime boundary (tool execution rejects out-of-scope calls), not just by prompt. +- Until then, a "read-only analyst" custom agent is a *persona*, not a *boundary* — documented as such wherever custom agents are exposed. +- This incident is also why scoping matters beyond security: the Data Assistant failed precisely because it could reach tools whose disciplines it didn't carry. + +## Non-goals + +- **Not** removing the multi-agent system — binding, API selection, eval, and channels all need it. +- **Not** an intent router between sibling agents — the skills mechanism is the per-intent behavior system; a router duplicates it with worse failure modes. +- **Not** merging Studio's pinned authoring persona — developer surfaces may keep specialist pins. + +## Risks + +| Risk | Mitigation | +|---|---| +| Fat prompt blurs registers (build turn sounds like an analyst) | intent preamble + per-skill discipline prose; L5 suite asserts both registers per deploy | +| Token cost of carrying all skill instructions | skills' instruction blocks are short; `triggerConditions` can structurally gate (e.g. authoring skills only in builder contexts) if cost shows up | +| Tenant expectations of capability-bounded custom agents | the gap is documented; tool scoping is the named follow-up before custom agents are marketed as boundaries |