s-m-r-t

Define a domain once, then give people and browser agents the same safe, structured application.

Comment

Inspiration

Most web applications are built for people to click and for agents to guess. Agents scrape labels and infer controls from fragile DOMs. s-m-r-t asks a different question: what if an application's real domain model, permissions, workflows, and interface also defined a deliberate browser-native tool surface?

Job hunting made that problem concrete. Finding opportunities, checking sources, triaging listings, recording notes, and preparing application packets are repetitive and stressful. They benefit from agent help, while final approval and employer submission should remain unmistakably human decisions.

What it does

s-m-r-t is the entry. It is a TypeScript framework for building operational applications around one typed domain model. Decorated business objects generate aligned persistence, REST, CLI, MCP, WebMCP, browser-data, and AI surfaces. WebMCP is not a separate demo API pasted onto an application: it is a governed browser projection of the same model and application contracts.

For the challenge, s-m-r-t gained:

  • canonical WebMCP definitions for deliberately API-exposed models;
  • authenticated execution through the existing REST boundary;
  • explicit exposure policies, effect classification, tool budgets, and namespaces;
  • lifecycle-safe registration through document.modelContext;
  • mounted form-control and data-surface adapters, giving agents and people the same UI state;
  • staged form edits requiring human review;
  • bounded queries and durable actions with stable identity and confirmation boundaries;
  • declarative view intents and layered playbooks that make the agent surface statically knowable;
  • local, self-hosted, and managed-cloud runtime profiles preserving the same tools and policies.

Iolaus is the demonstration application built with s-m-r-t. It is a local-first, single-user employment-search app using SQLite. A browser agent inspects source health, browses and investigates fictional job listings, records a triage decision and note, advances the queue, opens a shortlist, and inspects an application packet. Those actions update the same state the person sees. There is intentionally no WebMCP tool for final approval or employer submission.

Why WebMCP is essential

Without WebMCP, the agent needs brittle DOM automation or a separate privileged integration. With s-m-r-t, each page advertises bounded tools through document.modelContext. Those tools carry effect metadata, use authenticated application routes, respect field and exposure policies, and disappear with the page lifecycle. Mounted view tools change the same state the person sees, while background queries inspect data without disturbing the view.

The collaboration is legible: the agent performs structured work, the person sees its results, and sensitive transitions remain behind explicit human review. The implementation is reusable across application domains instead of being tied to one job board or agent harness.

How we built it

s-m-r-t is a pnpm TypeScript monorepo. Its scanner reads @smrt() declarations and emits manifests, schemas, routes, clients, and canonical tool descriptors. @happyvertical/smrt-web validates and registers generated and bespoke browser tools. @happyvertical/smrt-svelte binds those contracts to mounted forms and data surfaces. Its application runtime composes SQLite/local, PostgreSQL/self-hosted, and managed-cloud profiles without changing domain objects or WebMCP policy.

The execution path fails closed. The decorator controls model-operation exposure; authenticated REST remains the authorization boundary; undeclared effects are classified as destructive; sensitive fields are omitted; stale tools refuse execution; and staged edits cannot self-confirm. Integration fixtures exercise generated definitions, authentication failures, registration lifecycle, policy changes, mounted UI tools, and cross-profile parity.

Iolaus consumes published s-m-r-t packages and provides an isolated demo profile. pnpm demo:prepare builds and migrates private SQLite state, seeds visibly fictional opportunities and crawl provenance, starts a loopback-only server, and opens a one-time owner handoff. pnpm demo:smoke runs an authenticated browser proof and verifies both the available capabilities and the absence of approval/submission tools.

Challenges we ran into

The hardest problem was preserving one security and lifecycle model across generated model tools, page-mounted controls, custom component tools, and multiple runtime profiles. A capability policy is only useful if every registration path passes through it. We also had to separate discovery from authorization, exclude sensitive candidate fields, and prevent remounts or policy changes from leaving stale tools behind.

The local-first install introduced another systems challenge: safe owner bootstrap, idempotent SQLite setup, private on-device state, deterministic fixtures, and recovery commands all had to work without weakening the deployed application model.

Accomplishments that we're proud of

  • WebMCP is a first-class generated framework surface, not a hand-built endpoint for one demo.
  • The same declarations drive persistence, APIs, MCP, WebMCP, clients, and knowledge artifacts.
  • Human-visible controls and agent commands converge on shared registries and state.
  • Effect policy and human approval boundaries are explicit and testable.
  • Iolaus installs locally and proves a useful workflow without transmitting an application.
  • Cross-profile fixtures verify that infrastructure choices do not silently change the agent surface.

What we learned

WebMCP works best as an application architecture concern, not a thin automation layer. Browser tools should derive from the same source of truth as data and authorization. A strong human-agent experience also needs bounded inputs, visible shared state, effect metadata, lifecycle cleanup, deterministic testing, and carefully chosen places where the agent must stop.

What's next for s-m-r-t

We will continue hardening conformance across generated, mounted, and declared agent surfaces; improve route-aware capability discovery; and make the one-prompt local installation pattern reusable for other s-m-r-t applications. Iolaus will remain a real-world proving ground while preserving private local data and human control of external actions.

Source and testing

Both repositories are MIT licensed. The deterministic demo uses Node.js 24.18+, pnpm 11.24.0, and a WebMCP-capable browser. Clone Iolaus, enable Corepack, run pnpm install --frozen-lockfile, then pnpm demo:prepare. Run pnpm demo:test and pnpm demo:smoke for the repeatable proof. The fixture is fictional, local, and never contacts an employer.

Built With

Share this project:

Updates