s-m-r-t
Open the s-m-r-t source on GitHub Switch to dark color scheme

Interaction

Human-Agent Interaction

Persons and application agents use one declared interaction model. The model keeps meaning, proposals, consent, and authority explicit.

Keep each concern in its section

Interaction explains how persons and agents communicate and agree on meaning and control.

UI

UI renders the controls, state, confirmation, and feedback for an interaction.

Open UI →

Framework

Framework explains manifests, registries, generated operations, and authority.

Open Framework →

Tooling

Tooling explains developer and coding-agent workflows around the application.

Open Tooling →

Reference

Reference lists the complete interface, security, and package contracts.

Open Reference →

Learn the interaction model

01 Human-agent communication

The application supplies the meaning and authority. Chat and voice supply another way to request the same bounded work.

Read concept →02 Control discovery and meaning

An adapter asks the form what each control means. It does not guess from the control position or visible text.

Read concept →03 Commands and lifecycle

An agent can prepare a change without making the change. The person can review the proposal before the application applies it.

Read concept →04 Input sources and provenance

The form receives the same small command shape from each adapter. It still records which adapter requested the command.

Read concept →05 Consent, sensitivity, and authority

Knowing that a control exists is not permission to use it. Policy, control state, and user consent still decide each request.

Read concept →

Interaction 01

01

Communicate through shipped application interfaces

People and application agents can use natural language, chat, and voice. Each interface connects to declared operations or controls at an explicit application boundary. Verified against s-m-r-t 0.42.4

Natural language uses declared meaning

Generated MCP and WebMCP descriptions give an agent names, inputs, and constraints for declared operations. The control registry gives an adapter the equivalent description for visible controls.

  • The agent requests a declared operation instead of inferring an action from screen pixels.
  • The application resolves the request through its principal, tenant, permission, and field rules.
  • Natural-language input does not create a second application-logic path.

Chat keeps the tool boundary explicit

smrt-chat ships rooms, messages, agent sessions, streaming clients, and server-controlled tool lists. Its service checks membership and keeps generated model writes read-only.

  • An agent session stores the allowed tool names for that conversation.
  • The server offers and executes only tools that the current principal can use.
  • A product adapter can translate a trusted chat request into a control command.

Voice uses the same application boundary

smrt-svelte ships browser speech-to-text, text-to-speech, and language-model adapters. Its provider-backed form also owns spoken-input behavior.

  • A voice adapter identifies its command source as voice.
  • The rich form can collect spoken values through the configured browser AI adapters.
  • smrt-chat voice sessions bind a gateway session to the tenant, actor, persona, and conversation.

Know the current connection limit

The packages do not ship one general adapter that connects every chat or voice request to every form. The application selects the forms, commands, and transports that it exposes.

  • Installing smrt-chat does not let a chat agent operate all controls.
  • The provider-free smrt-ui form has no chat, voice, or model dependency.
  • The interaction registry records command context but does not authenticate its actor.

Interaction 02

02

Discover a control by identity and meaning

A control publishes a stable address, human-readable meaning, choices, constraints, sensitivity, capabilities, and current state. Verified against s-m-r-t 0.42.4

Use a stable control identity

Each address combines a formId and controlId. An optional subject identifies the record or application object that the form edits.

  • formId identifies the form without using its position in the page.
  • controlId identifies one control inside that form.
  • The optional subject has a type, an id, and an optional label.

Publish meaning and constraints

Metadata describes the control kind, label, description, options, constraints, unit, sensitivity, readable state, writable state, and capabilities.

  • Options include a value, label, and optional disabled state.
  • Constraints can include required, minimum, maximum, step, length, and pattern rules.
  • Capabilities state which read, navigation, explanation, validation, and mutation actions are available.

Inspect the current state

list and get return a snapshot with metadata and runtime state. Runtime state can report disabled, read-only, valid, and validation-message values.

  • A readable control can include its live value.
  • A staged proposal appears separately from the live value.
  • A redaction flag tells the adapter when a live or staged value is not available.

Derive capabilities from real handles

The registry derives default capabilities from the handles that a control registers. A control can declare a narrower capability list when the application requires it.

  • A control needs a value reader before the registry advertises read.
  • A control needs a value writer before the registry advertises stage, apply, or undo.
  • Secret controls never advertise read or mutation capabilities.

Interaction 03

03

Move from inspection to a confirmed change

The interaction lifecycle separates discovery, guidance, validation, a proposed value, and an approved live change. Verified against s-m-r-t 0.42.4

Follow the command lifecycle

Use the registry in this order when an agent helps with a control. The focus action is also available when an adapter must move keyboard focus.

  • 1. Inspect the control with list or get.
  • 2. Reveal or highlight the applicable control.
  • 3. Explain its meaning, options, constraints, sensitivity, and capabilities.
  • 4. Validate the current value with the control rule.
  • 5. Stage the proposed value.
  • 6. Apply the reviewed value after confirmation.
  • 7. Clear the value or undo the last registry change after confirmation.

Stage without changing the live value

Stage stores a proposed value in the registry. Stage does not call the control writer and does not change the live value.

  • The next snapshot shows the live value and staged value separately.
  • Staging an agent proposal does not require confirmation under the default policy.
  • An application can use a stricter custom policy before it accepts a staged proposal.

Confirm agent mutations

An agent apply, clear, or undo command returns human_confirmation_required under the default policy for an otherwise-permitted control, regardless of confirmed — a more specific refusal (sensitive, non-writable, disabled) still takes precedence. Only a human, through a real local click routed via executeLocalControlCommand, can apply, clear, or undo.

  • Apply uses the staged value unless the command supplies a direct value.
  • Apply stores the previous value for undo and then validates the new value.
  • Clear stores the previous value before it calls the control clear handle.

Keep undo inside its real boundary

Undo restores a value from the current interaction registry history. It does not reverse a saved server record or an external operation.

  • Each control has its own in-memory undo history.
  • An empty history returns nothing_to_undo.
  • The application owns any transaction or persisted-record rollback.

Interaction 04

04

Preserve the source of each command

User, voice, agent, tutorial, and test adapters use one control command contract. Command context keeps the source attached to execution and events. Verified against s-m-r-t 0.42.4

Use one command contract

Every adapter sends a command and a ControlCommandContext. The context source is user, voice, agent, tutorial, or test.

  • User identifies direct user-interface input.
  • Voice identifies a spoken-input adapter.
  • Agent identifies an application-agent request.
  • Tutorial and test identify guided and automated operations.

Keep context with interaction events

The registry includes command context in staged and completed command events. Subscribers can observe the source, confirmation state, actorId, and sessionId.

  • Registered and unregistered events identify control lifecycle changes.
  • Staged events identify the proposal and its source.
  • Command events include the request, context, result, identity, and timestamp.

Do not confuse a source label with authentication

Command context preserves provenance inside the registry, but the registry does not authenticate actorId or sessionId. The trusted adapter supplies and verifies that context.

  • actorId and sessionId are optional correlation values, not credentials.
  • An adapter must pass its real source instead of relying on the default user context.
  • Application authorization remains outside the transport-neutral registry.

Persist an audit trail when the product needs one

The subscribe method reports live interaction events. The registry does not store a durable audit log after the page or registry ends.

  • An application can send selected events to its authorized audit service.
  • The audit service must minimize values and protect sensitive context.
  • Tests can subscribe to the same events without a separate control API.