|
|
---
|
|
|
title: Agent — the delegation axis
|
|
|
type: reference
|
|
|
audience: human + agent
|
|
|
authority: E1 architecture — the agentic axis: the delegation model, the actor primitive, the participation contract, the minimum contracts, the a11y + threat doctrine
|
|
|
status: current — F0 doctrine (track PLAN-agent.md); decisions D-AG.1–11 + ⚖️1/2/3 signed 2026-07-21
|
|
|
sources:
|
|
|
canon: docs/CANON.md (the `delegate` family, ch. 29 of the book)
|
|
|
plan: docs/process/PLAN-agent.md (execution record — process, not doctrine)
|
|
|
review: docs/process/TRIAGE-revision-externa-agente.md (4-reviewer external critique)
|
|
|
---
|
|
|
|
|
|
# Agent — the delegation axis
|
|
|
|
|
|
> An **agent** is another actor. Not a mode, not a chat widget, not a wrapper
|
|
|
> around an LLM SDK. activeUIX already asks, in its semantic canon, _"¿quién
|
|
|
> actúa ahora?"_ — the `delegate` family (book ch. 29). The agent axis is the
|
|
|
> materialization of that family: the machinery by which **an actor other than
|
|
|
> the user** can be invoked from, and participate in, any component of the
|
|
|
> ecosystem — with the same events, the same undo, the same permissions, the
|
|
|
> same accessibility, and the same perceptual semantics that a user's action
|
|
|
> already gets.
|
|
|
|
|
|
This chapter is the standing doctrine — the **WHY**. What a conformant
|
|
|
implementation must actually do is specified normatively, with citable
|
|
|
requirement ids, in
|
|
|
[`spec/delegation-contract.md`](../spec/delegation-contract.md) (`DRAFT`); when
|
|
|
the two disagree about a requirement, the specification governs and this
|
|
|
chapter is corrected. The dated execution record (phases, signed decisions,
|
|
|
per-item work) lives in [`process/PLAN-agent.md`](../process/PLAN-agent.md) —
|
|
|
process, not truth.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 0. Why an axis, not a component (and the reference pass)
|
|
|
|
|
|
The framework's own rule is to **study reference implementations before
|
|
|
designing** (as it did for the framework itself in `comparison.md`). The
|
|
|
agentic-UI field, surveyed 2026-07, converges on a small set of contracts —
|
|
|
and diverges from activeUIX in exactly the places that make this axis worth
|
|
|
building.
|
|
|
|
|
|
| Concern | Field convergence | activeUIX position |
|
|
|
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
|
| Readable context | CopilotKit `useCopilotReadable`: NL-description + value, hierarchical (parentId), per-readable gating | `reads` in the per-component manifest; **push→pull** index + `read(instanceId)` on demand, prioritized by focus/viewport (a UIX-native signal none of them have) |
|
|
|
| Frontend tool calling | CopilotKit `useCopilotAction`, Vercel AI SDK tools, MCP tools; roundtrip closes via a `role:'tool'` message | `acts` in the manifest → the component's **existing public API**; result typed by sium, failures mapped to `delegate` verbs |
|
|
|
| Protocol / streaming | AG-UI: 17 events / 5 categories (run · text deltas · tool-calls · state · custom); triple start/content/end; state = snapshot + JSON-Patch delta (RFC 6902), resync by re-snapshot | Own protocol **mirroring AG-UI** (parity baseline, à la `ethereal` ↔ floating-ui); snapshot-per-turn in v1, delta reserved |
|
|
|
| Human-in-the-loop | Two shapes: pre-act approval (CopilotKit renderAndWait) + mid-run interrupt/elicitation (LangGraph interrupts, MCP elicitation). AG-UI models approval as a _confirmation-tool_, no separate primitive | The `delegate` cycle as **observable run states**; on the wire, review/elicitation ride the confirmation-tool shape (states in the motor, interop on the cable) |
|
|
|
| Embedded-UI security | MCP Apps (SEP-1865): sandboxed iframes, JSON-RPC host↔UI, **the host controls authorization** | The app is the ceiling of autonomy (D-AG.7); capabilities never self-authorize |
|
|
|
| Provider coupling | Most are React-first; **none ship a Svelte-native path** | Svelte-5-native by construction; provider adapters isolated behind a port |
|
|
|
|
|
|
**The gaps nobody fills** — and where this axis earns its keep:
|
|
|
|
|
|
- **A perceptual semantics of delegation.** No surveyed framework has a
|
|
|
vocabulary for _who acts_ rendered across sound / motion / a11y. The
|
|
|
`delegate` family is exactly that, and it predates the LLM wave.
|
|
|
- **Transactional undo of a run** (one delegation = one undo step) and
|
|
|
**reversibility declared by effect**, not by capability.
|
|
|
- **Accessibility of autonomous action**: attributed announcements, no
|
|
|
focus-theft, reduced-motion of the presence indicator.
|
|
|
- **Causal actor attribution** across an async, cross-component cascade —
|
|
|
synchronous, unforgeable, without a global async monkey-patch. A
|
|
|
browser-first UI framework that gets this right has no shipping precedent.
|
|
|
|
|
|
The conclusion of the pass: the correct shape is an **orthogonal axis** —
|
|
|
engine (an art) + per-component participation contract + registry + a few own
|
|
|
surfaces — not a monolithic agent component that would import every component
|
|
|
and invert the dependency direction. It instantiates the same anatomy every
|
|
|
other cross-cutting axis (sound, language, theme, motion) already uses.
|
|
|
|
|
|
Rejected alternatives, for the record: _protocol-only, no engine_ pushes the
|
|
|
state machine, budgets and elicitation into every app (re-implemented N times);
|
|
|
_agent-100%-backend_ kills frontend tool calling (the field's most load-bearing
|
|
|
contract) and the perceptual semantics; _generative-UI without manifests_
|
|
|
throws away the typed, auditable acts. Each can be layered on top later; none
|
|
|
can be the base.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 1. The thesis
|
|
|
|
|
|
> **The agent is another actor.** Everything downstream of that sentence is
|
|
|
> the design.
|
|
|
|
|
|
Four principles, none negotiable without re-signing:
|
|
|
|
|
|
1. **Actor-agnostic** (book ch. 29 §1). The axis never asks "is this an LLM?".
|
|
|
A macro, an automation rule, a workflow, a remote human approver and a
|
|
|
model are all just _another actor_. Nothing in the axis depends on a
|
|
|
concrete LLM provider. This is what lets the architecture outlive the LLM
|
|
|
market.
|
|
|
|
|
|
2. **The agent knows no components.** It never names `Palabras`, `Chronos`,
|
|
|
`Chat`. It sees only **capabilities** declared by whatever providers are
|
|
|
mounted. This keeps the dependency direction intact: the canon never
|
|
|
imports the axis.
|
|
|
|
|
|
3. **The golden rule — same public API, actor-dependent concretion.** The
|
|
|
agent acts through the **same public provider API** the app's own code
|
|
|
would call; the call path does not bifurcate. But the **semantic concretion
|
|
|
depends on the actor**: a component's existing events declare `delegate`
|
|
|
capacity (polymorphic events, `allowedFamilies` in the morfo contract) and
|
|
|
the provider concretes `{ family: 'delegate', verb: 'act' }` when the actor
|
|
|
is the agent. So the same `insert()` fires the same `runtime.trigger`, but
|
|
|
sema, eidos and the a11y layer read the correct answer to _"¿quién actúa?"_.
|
|
|
If a capability needs a door the public API lacks, that door is **promoted
|
|
|
to the component** through the normal route — never bypassed.
|
|
|
|
|
|
4. **Total degradation.** With the axis absent, every component works at 100%.
|
|
|
Manifest registration is a no-op; nothing a component owns depends on the
|
|
|
agent existing. See §4.
|
|
|
|
|
|
A corollary the field taught us the hard way: **client-side budgets are UX
|
|
|
courtesy, not a security boundary.** The boundary lives where the credential
|
|
|
lives (a proxy/backend). The motor's budgets exist to drive the state machine
|
|
|
and the UX, and the doctrine says so honestly.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. The domain model
|
|
|
|
|
|
The axis is built around a **delegation**, not a conversation. A chat is one
|
|
|
surface that chains delegations; it is not the core (an agent can fill a
|
|
|
document with no conversation at all).
|
|
|
|
|
|
```
|
|
|
ActiveAgent — the session (long-lived; context across runs; identity)
|
|
|
└── Run — a delegation: budget, authorization, undo grouping, control return
|
|
|
├── Turn — one exchange with the model
|
|
|
│ └── CapabilityCall — a delegate.act on a provider (the only thing that mutates)
|
|
|
└── Context — snapshot of reads at turn open (§3)
|
|
|
```
|
|
|
|
|
|
Three readings this ladder settles:
|
|
|
|
|
|
- **The `CapabilityCall` is what mutates the world; the `Run` is the unit of
|
|
|
delegation.** A mutation without the delegation envelope (budget,
|
|
|
authorization, undo grouping, control return) is exactly what the doctrine
|
|
|
forbids.
|
|
|
- **The degenerate Run** — a single auto-authorized call — is the non-AI case
|
|
|
of the book (a macro, a rule, a workflow). It is a valid, cheap Run.
|
|
|
- **Initiative is modeled, not just actor.** Every Run carries
|
|
|
`initiative: 'user' | 'system' | 'scheduled'` — _why_ it acts, not only
|
|
|
_who_ — because it changes trust, announcement, audit and the autonomy
|
|
|
ceiling. The entry verb hints it: a cycle entered by `offer` is
|
|
|
system-initiative.
|
|
|
|
|
|
**Ambient mode** (always-on: autocomplete, predictive suggestions) is **out of
|
|
|
the axis in v1, reserved by name**: a `Subscription`/watcher emitting
|
|
|
`delegate.offer`, with coalesced micro-runs as future design. It is named so a
|
|
|
second, parallel agency system cannot grow in by the back door.
|
|
|
|
|
|
### The run state machine = the `delegate` verbs, literally
|
|
|
|
|
|
The states **are** the verbs — as _custody of control_, not as cognitive
|
|
|
phases. The model's own plan→tool→plan loop lives entirely inside `acting`
|
|
|
(across turns); the machine models who holds control, not how the agent thinks.
|
|
|
|
|
|
```
|
|
|
┌─────────── escalated ──────────┐ (non-terminal; timeout → returned)
|
|
|
▼ │
|
|
|
offered → planned → reviewing ⇄ authorized → acting ──┤
|
|
|
│ │ (re-entrant: (fixes the │ ▼
|
|
|
│ │ partial allowlist + │ returned ← control ALWAYS returns
|
|
|
│ │ approvals) budget) │ (outcome-typed)
|
|
|
└─────────┴──── cancelled ────────────────────────┘
|
|
|
```
|
|
|
|
|
|
- **Authorization fixes scope, not vibes.** `authorized` derives from the plan
|
|
|
a **capability allowlist + budget**; an act outside that scope ⇒ automatic
|
|
|
`escalate` to re-review (never a silent failure, never teatro). This makes
|
|
|
`reviewing` re-entrant from `acting`.
|
|
|
- **`returned` is outcome-typed**: `completed | partial | rolled-back |
|
|
|
aborted | error`, with a `reason` (`superseded` — the premise changed under
|
|
|
the run; `budget-exhausted`; `killed`). Mid-sequence failure **rolls back to
|
|
|
run-start by default** (the user authorized the whole plan, not half); a
|
|
|
capability may declare it accepts partial close.
|
|
|
- **`escalated`** is non-terminal, carries a typed `reason` (`elicitation |
|
|
|
insufficient-scope | budget-exhausted | out-of-plan`), and **auto-returns on
|
|
|
timeout** (an abandoned escalation still needs an exit).
|
|
|
- **Pause needs no new verb**: pause = `return` with resumable context; resume
|
|
|
= a fresh Run chained in the session — which coincides with AG-UI's `resume`
|
|
|
mechanics. Our semantics and its wire converge without trying to.
|
|
|
- **User interruption = immediate `return`**, never an error. A **global kill
|
|
|
switch** on the motor (`disable()`) sends every run to `returned(aborted)`.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 3. The participation contract
|
|
|
|
|
|
A component participates by declaring a **manifest** — the mirror of a sema
|
|
|
pack or a langs catalog, in its own tree (`src/uix/agent/components/{x}.ts`).
|
|
|
The manifest satisfies **structural contracts defined by the art**
|
|
|
(`AgentCapability` / `AgentRead`: string ids, Standard-Schema args via sium,
|
|
|
opaque handler) — the MotionDom / SceneDom port pattern — by typing against the
|
|
|
provider's public API on the uix side. Soma/uix types never cross into the art;
|
|
|
the opaque handler grants location-transparency for free (a reserved path to
|
|
|
distributed delegation).
|
|
|
|
|
|
- **Model-facing projection.** TypeScript never reaches the model. Every read
|
|
|
and act carries a natural-language `description`; args project as **JSON
|
|
|
Schema** (a sium→JSON-Schema emitter), with **size limits per arg** as part
|
|
|
of the contract. Traits annotate each act for the reasoner (cost, latency,
|
|
|
stability, staleness) — the MCP tool-annotations pattern.
|
|
|
- **Instances and context — push→pull.** An always-present **index** (stable id
|
|
|
- type + human label + one-line summary, hierarchical) plus deep reads as a
|
|
|
**pull capability** (`read(instanceId)`), prioritized by **focus/viewport**;
|
|
|
addressing ambiguity ("the editor", with two mounted) ⇒ **elicitation, not a
|
|
|
heuristic**. `available` is a reactive predicate per act; a
|
|
|
`capabilities-changed` event refreshes the toolset between turns.
|
|
|
- **Results and failures** are sium-typed; a result carrying third-party
|
|
|
content is as untrusted as an imported document (same origin doctrine, §5).
|
|
|
`unknown-capability` (a hallucinated tool) returns as a tool-result for
|
|
|
self-correction, bounded by budget.
|
|
|
- **Altitude, not RPC.** Capabilities are **mechanical world-mutations**, few
|
|
|
and at the right altitude (`replaceRange`, not twelve micro-inserts).
|
|
|
Semantic operations (`summarize`, `translate`) are the _model's_ cognition or
|
|
|
a reserved agent-side "skills" tier (the MCP-prompts analogue) — never lodged
|
|
|
in the component, which would invert the dependency direction.
|
|
|
- **Maturity tiers.** A manifest declares its tier — `reads-only` →
|
|
|
`reversible acts` → `full acts` — so the ~110 canon components adopt
|
|
|
incrementally without gating the axis; the guard audits the declared tier.
|
|
|
- **Reversibility is by effect, not by capability.** External effects
|
|
|
(send / publish / notify) are irreversible by definition; the reversion
|
|
|
authority is the component's **native history**, never orca compensation.
|
|
|
- **OCC.** Each read exports a `_version`; each act must carry it; a mismatch
|
|
|
is a recoverable `StateStaleError` (re-read → re-plan) — the answer to TOCTOU
|
|
|
(§5).
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. Minimum contracts (the §0 row) and degradation
|
|
|
|
|
|
Following the framework's rule that every change derive from the module
|
|
|
contract table:
|
|
|
|
|
|
```text
|
|
|
Module Requires Optional When missing Error
|
|
|
agent AgentTransport port orca, perm, prefs, manifest registration is a NO-OP; only on invoking a
|
|
|
(app supplies it) connection, storage every component stays 100% functional capability with no transport
|
|
|
```
|
|
|
|
|
|
- The agent is an **app-level art** (factory `defineActiveAgent(...)`, the
|
|
|
auth/perm/cache pattern), not something `ActiveUix` builds in standalone.
|
|
|
Promotion to a read-only `uix.agent` accessor in attach mode arrives with the
|
|
|
canonical consumer (the scene-D4 precedent).
|
|
|
- **A component with a manifest MUST behave identically with the agent
|
|
|
absent.** The manifest is inert data until a running `ActiveAgent` reads it.
|
|
|
- Transport is **app-land by default** (the chat-family precedent: "the
|
|
|
transport stays app-land"); a server-authoritative `svrs/agent` is a
|
|
|
conditioned future initiative, never the v1 assumption. Adapters live in
|
|
|
`$agent/adapters/*` outside the main barrel; a **deterministic
|
|
|
`ScriptedAgentTransport`** is first-class, so static demos and component
|
|
|
tests run with **real instances, no mocks**.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 5. The actor primitive (⚖️2) — causal attribution
|
|
|
|
|
|
The load-bearing decision of the axis. When the agent's act on component A
|
|
|
triggers events that cascade to mutate component B, **B's emission must carry
|
|
|
the correct actor** — or sema announces the agent's secondary effect as "user",
|
|
|
a11y and audit-trail catastrophe.
|
|
|
|
|
|
**The answer is the OTel-baggage unification, corrected by the browser caveat.**
|
|
|
The actor is an **opaque, engine-minted token** (`ActorToken`, minted and
|
|
|
resolved only by `EngineAgent`; a non-token `USER` sentinel everywhere else, so
|
|
|
absence can never be confused with a minted token) carried as **one reserved
|
|
|
slot on the causal envelope the framework already propagates** — `OrcaEventMeta`
|
|
|
on the orca path, the bus envelope's `context` bag on the bus path — inherited
|
|
|
depth-to-depth exactly as `traceId` is. It is read **synchronously** via
|
|
|
`actor?: ActorToken` on `TriggerOptions → SemanticSignal`, before the first
|
|
|
`await` in `EngineSemantic.emit`.
|
|
|
|
|
|
This **shares one propagation primitive** with the D-AG.9 trace port
|
|
|
(run = trace, CapabilityCall = span, **actor = baggage**) — distinct payloads,
|
|
|
distinct guarantees: the span export is async and loss-tolerant; the actor read
|
|
|
is synchronous and authoritative. Sharing the primitive avoids forking agency;
|
|
|
keeping the payloads distinct respects that sema cannot tolerate the
|
|
|
fall-to-root a tracer tolerates.
|
|
|
|
|
|
Why **explicit, not ambient**: native `AsyncContext`/ALS is the framework's own
|
|
|
orca mechanism, already adjudicated — in the browser (`als.ts` feature-detects
|
|
|
to `null`) it degrades to a root envelope with no actor, precisely the failure
|
|
|
this decision exists to avoid. A faithful zero-dep reimplementation is
|
|
|
impossible without Zone.js-style global monkey-patching (forbidden, and it
|
|
|
still cannot cover a bare `await`). So **ambient auto-fill is opportunistic
|
|
|
sugar; the explicit envelope is the guarantee** — which is exactly how
|
|
|
OpenTelemetry-JS actually works (baggage on a propagated context, synchronous
|
|
|
`StackContextManager` in browsers, `async_hooks` server-side only). This is the
|
|
|
industry consensus in one line: _explicit provenance bound to the message,
|
|
|
ambient as sugar_ — OTel propagators inject/extract explicitly, CaMeL binds an
|
|
|
unforgeable capability tag to the value, Yjs attributes derived mutations by an
|
|
|
explicit per-transaction `origin`.
|
|
|
|
|
|
Scope and honesty:
|
|
|
|
|
|
- **Anti-forgery** (the reason the token is opaque): no site outside
|
|
|
`arts/agent` may construct an `ActorToken` or write the reserved actor key;
|
|
|
the token is never wire-serialized (the trace-export boundary emits a
|
|
|
non-authoritative `'agent'` label only). The `ActorToken` **type** lives in a
|
|
|
leaf below both orca and agent to avoid an orca→agent cycle; minting
|
|
|
authority stays in `EngineAgent`. On the bus path the actor rides the untyped
|
|
|
`context` bag, so its anti-forgery defense is the `agent-check` lint, not the
|
|
|
type system.
|
|
|
- **The guarantee is scoped.** It is delivered for the **explicitly-authored
|
|
|
A→B bridge** that threads `opts.actor`. An agent driving a stock component
|
|
|
through its public API has no call-site to thread it and, in the browser,
|
|
|
resolves to the `USER` sentinel — best-effort, out of v1. **In-scope
|
|
|
attribution rides the model-derived `data-actor`** paint (eidos reads the
|
|
|
reactive run state during `acting`), which needs no threading; the envelope
|
|
|
baggage is specifically for **out-of-scope secondary effects + audit**.
|
|
|
- **The primitive ships first, the propagation retrofit later.** The minimal
|
|
|
primitive (branded token + `USER` sentinel + private registry + anti-forgery
|
|
|
guard + synchronous `opts.actor` read) is built up front. The
|
|
|
~6-seam envelope-propagation retrofit (`OrcaEventMeta.actor`,
|
|
|
`OrcaALSContext.actor`, `ctx.emit` forwarding, `buildChildEnvelope` copy,
|
|
|
bus-subscription forwarding, `publishCausedBy` parent-merge) is **deferred to
|
|
|
the phase with a real out-of-scope async-cascade consumer**, gated by the
|
|
|
guard's drift check that ambient is never the sole carrier on a
|
|
|
cross-component bridge.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. Authorization, consent and autonomy
|
|
|
|
|
|
Three levels — `suggest | review | auto` — resolved prefs-style (the app is the
|
|
|
ceiling; the user adjusts downward; a capability may demand _more_ control,
|
|
|
never less; **deny-overrides**). Irreversible ⇒ `review` always.
|
|
|
|
|
|
- **Dynamic risk by payload**: the manifest declares a risk classifier over
|
|
|
args; `auto` escalates to `review` per invocation (same capability, different
|
|
|
blast radius).
|
|
|
- **Context origin lowers the ceiling** — the unification that dissolves
|
|
|
prompt-injection from an open threat into a policy row: each read carries an
|
|
|
origin tag (`authored-by-user | imported | third-party | other-participant`);
|
|
|
**any untrusted origin in the turn lowers the ceiling** (to `review`, or
|
|
|
`suggest` for sensitive capabilities). This is the industry pattern (forced
|
|
|
human approval when untrusted content is in context) expressed through
|
|
|
machinery already designed.
|
|
|
- **Initiative affects ceilings**: autonomous initiative (`system` /
|
|
|
`scheduled`) defaults stricter than user-requested.
|
|
|
- **Authorization is bound to state, not prose** (TOCTOU): review computes
|
|
|
against a fingerprint `F` of the relevant reads; authorization binds to `F`
|
|
|
**plus a TTL**; drift ⇒ recompute the diff (identical → optional
|
|
|
auto-re-approve; different → re-review). The user↔agent concurrency problem
|
|
|
is the OT/CRDT model (Yjs) — adopt the mental model, not the library.
|
|
|
- **Approval fatigue**: persistent grants ("always allow X") carry a TTL and an
|
|
|
explicit scope (session / component / act type); review shows the **concrete
|
|
|
proposed change in the app's own domain, never prose** (amended 2026-07-22 —
|
|
|
see "The review surface" in §7: the content of a review is app-owned). A
|
|
|
`capabilities-changed` event re-gates grants.
|
|
|
- **perm** governs only server-touching scopes (enforced in the proxy /
|
|
|
server-side tool-loop); the base case is local consent with no perm
|
|
|
dependency. **`reads` are permission subjects symmetric to `acts`** —
|
|
|
sensitive components (credentials/passwords) never register reads.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 7. Semantics, presence and accessibility
|
|
|
|
|
|
- The motor **emits nothing** (an art with no DOM); it exposes the run as
|
|
|
reactive state. **Surfaces** declare the cycle in their morfos (`delegate-*`);
|
|
|
`sustain-processing` belongs to **Aura** (state-bound persistence, cleared on
|
|
|
run close). **Actuated components** concrete `delegate.act` via
|
|
|
`allowedFamilies` with the actor context.
|
|
|
- **A run above `suggest` requires a mounted presence surface** (a minimal
|
|
|
Aura). A run in `acting` with nowhere to emit its cycle is perceptually
|
|
|
invisible — a direct contradiction of _"¿quién actúa?"_. The motor refuses
|
|
|
(or warns) on entering `acting` without one; this is mechanically verifiable.
|
|
|
- **Write-scope is declared**: a run declares its scope (component | part |
|
|
|
range); hold and paint apply only there.
|
|
|
- **The review surface** (amended 2026-07-22 — supersedes the discarded
|
|
|
"review-card" idea, a dev-tool anchoring). The framework/app split is:
|
|
|
the FRAMEWORK owns the cycle states expressed perceptually (`reviewing` /
|
|
|
`escalated` surfaced by the presence surface, with authorize/reject/cancel
|
|
|
affordances — Aura already does this), the "proposed by another actor"
|
|
|
semantics, and the attributed announcements. The APP owns the CONTENT of
|
|
|
what is being reviewed, rendered in its own domain (a document shows its
|
|
|
proposed blocks, a calendar its pending events, a form its suggested
|
|
|
values) — in context, where the user already is. A git-style diff card is
|
|
|
a legitimate construct for a specific application (e.g. a code tool built
|
|
|
ON the framework); it is never canon.
|
|
|
|
|
|
The **a11y contract** — no framework has this; documenting it fixes the pattern
|
|
|
others will cite:
|
|
|
|
|
|
1. **One `polite` live region owned by Aura**; announcements **attributed**
|
|
|
("Agente: …") and **coalesced by plan/batch** — never per delta, never per
|
|
|
act (WCAG 4.1.3).
|
|
|
2. **No focus-theft — a motor invariant** (WCAG 3.2.1 / 3.2.2), not each
|
|
|
surface's courtesy.
|
|
|
3. `aria-busy` on the region being mutated during streaming; a completion
|
|
|
announcement on close **that carries the outcome** — a failure returning
|
|
|
control silently is the same invisibility as an act with nowhere to emit.
|
|
|
The surface expresses it with THREE terminal events, intent intrinsic to
|
|
|
each (a dynamic intent has nowhere to live: the trigger options carry none
|
|
|
and a morfo's `fromProp` binds to a public prop, not to machine state):
|
|
|
`completed` → fulfill · `aborted`/`partial` → no intent (a decline is
|
|
|
absence, not loss) · `error`/`rolled-back` → loss. All three stay
|
|
|
TRANSIENT: once control is back there is no custody to claim, so a
|
|
|
persistent alarm would make the surface lie about who holds it — the
|
|
|
failure's DETAIL belongs to the app, in its own domain. Binding a tone to
|
|
|
this structural family is the sanctioned `BK-FRAME-NO-INTENT` exception
|
|
|
(book-updates A-1) and costs a written `intentRationale`: the engine emits
|
|
|
nothing and no `signal`/`commit` event exists on the presence surface, so
|
|
|
the consolidated return is the outcome's only expressive site.
|
|
|
4. Elicitations are **dismissible / postponable**, not modal by default
|
|
|
(WCAG 2.2.4). An elicitation is a **typed question**, so its surface is a
|
|
|
form in context — not a conversation. The schema the agent asks with is the
|
|
|
same projection its capability args already travel through (sium →
|
|
|
JSON Schema), read in the opposite direction; binding elicitation to a chat
|
|
|
would make a general contract depend on one product shape.
|
|
|
5. **A global keyboard exit** (an Esc-like doctrine): cancel / return reachable
|
|
|
without a mouse. Aura uses `reduce: 'static-frame'`, never `hide`.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 8. Threat model
|
|
|
|
|
|
The axis builds, by construction, the classic **"lethal trifecta"** (Willison):
|
|
|
private data + untrusted content + the ability to act. The doctrine treats it
|
|
|
head-on:
|
|
|
|
|
|
- **Prompt injection.** Reads carry an **origin tag** (per §6); untrusted
|
|
|
origin lowers the autonomy ceiling (the primary mitigation, folded into
|
|
|
policy). Adapters **spotlight** (delimit/mark) non-authored content so the
|
|
|
model treats it as data. Reserved for depth: dual-LLM (a privileged planner
|
|
|
that never sees untrusted content; a quarantined model that returns only
|
|
|
symbolic references) and CaMeL-style capability/data-flow tracking —
|
|
|
philosophically close to the framework's structural ports. Checklist anchors:
|
|
|
OpenAI instruction-hierarchy, OWASP LLM Top 10 (LLM01).
|
|
|
- **TOCTOU.** Authorization bound to a read fingerprint + TTL (§6).
|
|
|
- **Actor forgery.** The opaque engine-minted token + the `agent-check` guard
|
|
|
(§5).
|
|
|
- **Run recovery.** A minimal **write-ahead journal per run** via `$storage`
|
|
|
(sessionStorage suffices in v1) records authorizations + applied acts and
|
|
|
detects orphaned runs on reload. The audit-trail is defined **now** as an
|
|
|
OTel-shaped trace port (run = trace, CapabilityCall = span); the storage
|
|
|
vehicle arrives later. (orca cannot be a store — its own rule.)
|
|
|
- **Kill switch, multi-user, i18n.** A global disable (§2). User identity in
|
|
|
the actor vocabulary is reserved (multi-user arrives with `connection`). The
|
|
|
agent's `identity` / system-context carries the effective locale; the agent
|
|
|
announces in the langs-axis language like any surface.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 9. What this axis is NOT
|
|
|
|
|
|
- **Not a chat.** Chat is one surface (a participant + a composer) that chains
|
|
|
runs; the axis works with no conversation at all.
|
|
|
- **Not an LLM integration.** It is a theory of delegation; a model is one kind
|
|
|
of actor. Nothing depends on a provider SDK (adapters are isolated and
|
|
|
optional).
|
|
|
- **Not a parallel "AI mode".** It preserves every framework invariant —
|
|
|
dependency direction, semantics, events, public API, undo, a11y — instead of
|
|
|
forking them. A component with a manifest is the same component.
|
|
|
- **Not a component that knows components.** It sees capabilities, never types.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 10. To go deeper
|
|
|
|
|
|
- Vocabulary of `delegate` (families, verbs, intent policy): [`CANON.md`](../CANON.md).
|
|
|
- The whole-system layering the axis plugs into:
|
|
|
[`architecture/active-architecture.md`](./active-architecture.md).
|
|
|
- The arts pattern (`Engine*` / `Active*`, ports, degradation):
|
|
|
[`arts/README.md`](../../src/arts/README.md).
|
|
|
- Execution record, signed decisions, phases:
|
|
|
[`process/PLAN-agent.md`](../process/PLAN-agent.md).
|
|
|
- The external critique that hardened this doctrine:
|
|
|
[`process/TRIAGE-revision-externa-agente.md`](../process/TRIAGE-revision-externa-agente.md).
|
