AdminConsole
Stateful journeys/AI & Location
statefulagent run aggregate
Mappls MCP · approval-bound tool orchestration

Governed spatial agent run

Turn a natural-language spatial objective into an inspectable plan, obtain an exact least-privilege approval, execute allow-listed Mappls tools, and cite provider evidence without exposing credentials to the model.

Open implementation workshop Run verified appExplore lifecycle
Lifecycle state machine

Every state means something operational

A state is not a UI label. It determines which actor may act, what evidence exists, what may be retried, and how recovery proceeds.

01
asked

Asked

A stable run records the user's objective, scenario, actor, tenant, purpose, and bounded inputs before any provider access.

02
planned

Planned

A schema-valid allow-listed dependency graph, risk class, scopes, argument bounds, and canonical plan hash are available for inspection.

03
approved

Approved

An attributable person approved the exact plan hash, every required scope, purpose, data boundary, policy version, and expiry.

04
executing

Executing

A service-side lease owns execution and calls each Mappls tool only after dependencies and authorization are satisfied.

05
completedterminal

Completed

The grounded answer, structured outputs, exact tool evidence, provenance, citations, cost, and terminal audit event are committed.

06
rejectedterminal

Rejected

A named approver denied the proposed plan with an attributable reason and no provider calls occurred.

07
failedterminal

Failed

Execution stopped with a typed, secret-safe error and retained evidence for every completed step.

Command → decision → event

Transitions are attributable and retry-safe

Commands express intent. The aggregate validates current state and invariants, commits one new version, and emits a fact in the same transaction.

Command & actorAllowed fromResultIdempotency strategy
askApplication user
new aggregate
askedagent.question_received

Use a client-generated run command ID across network retries.

create_planAgent planner
asked
plannedagent.plan_created

Canonical objective, policy, planner version, and normalized plan produce one immutable hash.

approve_planHuman approver
planned
approvedagent.plan_approved

Bind approver decision to run version, exact plan hash, scopes, purpose, and expiry.

reject_planHuman approver
planned
rejectedagent.plan_rejected

Persist the review decision and reason under one command identity.

start_executionExecution service
approved
executingagent.execution_started

Acquire one lease only after recalculating plan hash and rechecking approval, scopes, expiry, and policy.

complete_executionExecution service
executing
completedagent.execution_completed

Commit terminal result, citations, audit, and outbox against the execution attempt identity.

Durable records

Persist enough to recover and explain

Keep provider responses, business identity, state, events, and side-effect delivery distinct so each can be reconciled safely.

Agent run

Durable objective, lifecycle, version, risk, actor, tenant, and purpose boundary.

runIdstateversiontenantIdquestionrisk

Plan manifest

Canonical tool graph, dependencies, arguments, requested scopes, and integrity identity.

planVersionplanHashplannerVersionstepsrequiredScopespolicyVersion

Approval grant

Independent attributable authority for one exact plan and bounded time window.

planHashapprovedByapprovedScopespurposeapprovedAtexpiresAt

Tool evidence

Resolved arguments, structured response, provider provenance, status, timing, and stable request identity.

toolCallIdstepIdtoolrequestIdprovenancecompletedAt

Grounded result

Answer and machine-readable outputs with per-step citations and inference labels.

runIdanswercitationsgeneratedAtmodelVersion
Non-negotiable rules

Protect truth at the aggregate boundary

  1. 1

    The model never receives Mappls or customer credentials.

  2. 2

    Only schema-valid allow-listed tools and bounded arguments can enter a plan.

  3. 3

    Approval names the canonical immutable plan hash and every required scope.

  4. 4

    An expired, superseded, partially scoped, or self-approved plan cannot execute.

  5. 5

    Every factual provider claim is traceable to retained Mappls provenance.

  6. 6

    Tool failures and persisted evidence never expose secrets.

Failure and recovery

Know what to do before it breaks

Recovery changes durable truth only through the same rules as normal operation. A timeout is an unknown outcome, not evidence that nothing happened.

Prompt or retrieved content asks for an unapproved tool

Detect

The proposed tool, scope, host, or argument is absent from the validated plan policy.

Recover

Reject the plan or stop execution and surface the exact policy denial for human review.

Plan changes after approval

Detect

Recomputed canonical hash differs from the approved plan hash.

Recover

Refuse execution, append a tamper or supersession event, and require a new review.

Provider call succeeds but the worker loses its response

Detect

Execution lease expires with an ambiguous step and stable request identity.

Recover

Reconcile by provider or application request identity before retrying, especially for side-effecting tools.

Tool output lacks provenance or contains a secret

Detect

Response-envelope validation or redaction policy fails.

Recover

Quarantine the output, stop the run safely, rotate any exposed secret, and retain only a sanitized incident record.

Operational telemetry

Observe the journey, not merely HTTP status

Measure state age, event health, retries, reconciliation, and sensitive-data access alongside latency and error rate.

  • Runs and time spent in asked, planned, approved, and executing states
  • Approval, rejection, expiry, and scope-reduction rate by risk class
  • Plan hash mismatch, policy denial, and prompt-injection detection
  • Tool latency, quota, retry, reconciliation, and cost by operation
  • Provider provenance and citation coverage
  • Sensitive-location access by tenant, actor, purpose, and retention class
  • Execution leases, orphaned attempts, outbox backlog, and restart recovery
Grounded implementation

Contracts, repositories, workshops, tutorials, and runnable evidence

Only explicitly indexed evidence is linked. Empty sections are not backfilled with invented endpoints or package names.