Intent Routing Architecture

A user types into Cursor: “I want to reduce agent noise.” A chat-completion wrapper would answer with tips. HUMΛN’s Companion classifies the turn as INTENT, shapes a brief, compiles a capability plan, runs autonomy and risk gates, and emits an intent_action the human can approve — or refuse.

human.ask(...) looks like a completion call. It is not. Behind it is a multi-stage pipeline from classification to provenance.

Scroll-stopper: The LLM never bypasses the scope check. The risk gate is enforced server-side — not by the model’s promises.

So that “AI does things” is governable: propose by default, auto only when reversible, approval real, provenance automatic.

The three classification modes

Mode	What it means	Output shape
QUESTION	The user wants information.	text answer with citations.
CONTEXT	Sharing context for later (no action expected).	Acknowledgment, session memory.
INTENT	The user wants something done.	text + intent_action block.

Within INTENT: fuzzy (not compile-ready) vs clear (compile-ready). Classification happens in the structured LLM response; the companion-agent layer parses and routes.

Step 1 — Fuzzy intent shaping

When the brief is fuzzy, Companion can:

1. Ask a clarifying question — “Fewer notifications, fewer agent runs, or different routing?”
2. Make a confident inference from session context and ask for confirmation.

Most agent demos skip this. Real intents are rarely clear on first try. HUMΛN bakes in shaping.

Step 2 — Clear intent → intent_action

{
  "classification": "intent",
  "text": "I'll propose scaffolding a connector package that consumes inbound webhook events.",
  "intent_action": {
    "tool_id": "humanos.scaffold.connector",
    "params": { "provider": "stripe", "direction": "consume" },
    "autonomy": "propose",
    "requires_approval": true,
    "reversible": true,
    "human_readable": "Scaffold a Stripe webhook consumer connector",
    "consequence": "Creates package skeleton + route registration plan; does not deploy.",
    "provenance_scope": "human_api:agents:invoke"
  }
}

Illustrative tool_id shape — the compiler resolves against the Capability Graph; your org’s installed capabilities may differ. Every field still matters: requires_approval is set by the risk gate, not the LLM; reversible constrains what auto may do.

Step 3 — /v1/intent compiles the brief

Shipped path: POST /v1/intent (MCP human.intent / Companion clear-intent compile). Execution of an approved plan uses human.call / POST /v1/agents/call under a delegation that includes the required scopes — a separate step from compile.

1. Brief validation
2. Capability discovery
3. Constraint solving
4. Plan emission (capability_resolution_plan)
5. Autonomy resolution (org profile ∩ user delegation)
6. Risk gating — irreversible / high blast-radius steps get requires_approval: true regardless of LLM claims

The plan is durable: stored, versioned, replayable.

Step 4 — human.call executes (human in the loop)

1. Scope check — does the delegation include provenance_scope? Else 403.
2. Approval check — if required, return pending_approval.
3. Pre-flight risk gate — against current policy, not plan-time only.
4. Execution
5. Provenance — who, scope, params, outcome, duration
6. Result + provenance ID

Failures: RFC 7807 application/problem+json with remediation.

Step 5 — Autonomy: observe, propose, auto

• observe — log only
• propose — surface intent_action, require approval (default)
• auto — only if reversible: true; risk gate enforces; LLM cannot self-upgrade

Most restrictive wins across org policy + user delegation. Users can add friction; they cannot remove it unilaterally.

Step 6 — Provenance at every step

Chain: user message (hashed) → classification + brief → plan ID → each human.call → approvals → result. Signed, append-only. Auditors get one ordered, verifiable trace.

Walkthrough: scaffold a Stripe webhook connector

1. Classification: intent, fuzzy → Companion asks consume vs emit
2. Refinement: “Consume.” Brief clear.
3. Compile: plan with scaffold → register route → generate manifest
4. Risk gate: scaffolding reversible; user’s read-heavy delegation lacks human_api:agents:invoke → surfaces for approval / wider mint
5. intent_action with “Run scaffolding”
6. User approves → human.call runs steps with provenance
7. Follow-up: Companion can propose config next — session carries intent state; user stays in control

What this enables

• LLM never bypasses scope check
• Risk gate is server-side
• Approval is real, not theatrical
• Provenance is automatic
• Reversibility is a hard gate on autonomy

Pair with the Autonomic Engine for model routing and delegation scope design for the grants that make invoke legal.

Go deeper

• Product: Companion, HumanOS
• Docs: HumanOS concepts, Delegations concepts
• Community: Autonomic Engine, Delegation scope design, Controlling execution lifecycle