DEV Community: StareBrain

Not Every Backend Tells You What Happened: Provider Capability Tiers in an AI Agent

StareBrain — Sun, 25 Oct 2026 04:54:59 +0000

Introduction

When an AI agent dispatches an action — send a message, book a slot, toggle a setting — it needs to know whether the action succeeded. But not every backend gives you the same quality of answer.

Some tell you exactly what happened. Some give you enough to figure it out. Some give you nothing at all.

If your agent treats all backends the same way, it will make wrong decisions when a provider goes quiet. The fix is to model capability explicitly before you dispatch — not after.

The Four Tiers

`enum class ProviderCapabilityTier {
    FULL,           // Confirms delivery + acceptance
    RECONCILABLE,   // No direct confirmation; can query state after dispatch
    PARTIAL,        // Confirms delivery only; acceptance unknown
    BLIND           // No confirmation, no queryable state
}`

FULL — The provider sends back a confirmed result. You know delivery happened and the action was accepted. Calendar providers with a write API, messaging platforms with delivery receipts.

RECONCILABLE — No direct confirmation on dispatch, but you can query the provider’s state afterward and compare against a pre-dispatch snapshot. The diff tells you what changed.

PARTIAL — The provider acknowledges receipt but can’t tell you whether the action was actually carried out. You know it arrived; you don’t know if it landed.

BLIND — Fire and forget. No receipt, no queryable state. You dispatched. That’s all you know.

Why It Matters Before Dispatch

The tier determines what your reconciliation strategy needs to be — and that decision has to be made before you dispatch, not after you’re already waiting for a response that isn’t coming.

`data class DispatchStrategy(
    val tier: ProviderCapabilityTier,
    val reconciliationKey: String?,
    val eligibleForReconciliationAt: Instant,
    val requiresManualVerification: Boolean
)

fun buildDispatchStrategy(
    tier: ProviderCapabilityTier,
    now: Instant
): DispatchStrategy {
    return when (tier) {
        ProviderCapabilityTier.FULL -> DispatchStrategy(
            tier = tier,
            reconciliationKey = null,
            eligibleForReconciliationAt = now,
            requiresManualVerification = false
        )
        ProviderCapabilityTier.RECONCILABLE -> DispatchStrategy(
            tier = tier,
            reconciliationKey = generateReconciliationKey(),
            eligibleForReconciliationAt = now.plusSeconds(CONSISTENCY_WINDOW_SECONDS),
            requiresManualVerification = false
        )
        ProviderCapabilityTier.PARTIAL -> DispatchStrategy(
            tier = tier,
            reconciliationKey = generateReconciliationKey(),
            eligibleForReconciliationAt = now.plusSeconds(CONSISTENCY_WINDOW_SECONDS),
            requiresManualVerification = true
        )
        ProviderCapabilityTier.BLIND -> DispatchStrategy(
            tier = tier,
            reconciliationKey = null,
            eligibleForReconciliationAt = Instant.MAX,
            requiresManualVerification = true
        )
    }
}

private const val CONSISTENCY_WINDOW_SECONDS = 30L`

Wiring It Into the Action Record

From the Oct 22 post, the ActionRecord carries delivery and acceptance state. The tier slots in alongside it:

`data class ActionRecord(
    val actionId: String,
    val dispatchId: String,
    val providerObjectId: String?,
    val tier: ProviderCapabilityTier,
    val dispatchStrategy: DispatchStrategy,
    val delivery: DeliveryState,
    val acceptance: AcceptanceState,
    val dispatchedAt: Instant,
    val confirmedAt: Instant?,
    val eligibleForReconciliationAt: Instant
)`

For a BLIND provider, eligibleForReconciliationAt is Instant.MAX — the record never becomes eligible for automated reconciliation. It stays DENIED_UNRESOLVED until a human or a higher-level signal resolves it.

For a RECONCILABLE provider, the consistency window enforces a minimum age before the reconciliation job touches the record — the same replication lag protection from the Oct 22 post.

The Rule

Model the tier at registration time, not at failure time. By the time dispatch has failed silently, it’s too late to decide how you were going to handle it.

Every provider your agent talks to gets a declared tier. Every action record carries the strategy that tier implies. Reconciliation and confirmation handling downstream just read the record — they don’t need to know which provider they’re dealing with.

Series so far:

Part 1: Two-axis state model + DENIED_UNRESOLVED
Part 2: Context propagation + confidence thresholds
Part 3: Late confirmation race + terminal state check
Part 4: Provider capability tiers ← today

Late Confirmation Race: Handling the Gap Between User Approval and Action Dispatch in Android AI Agents

StareBrain — Sat, 24 Oct 2026 03:56:17 +0000

There’s a timing problem in confirm-before-execute flows that’s easy to overlook until it causes a duplicate action: the window between when the user confirms and when the action actually dispatches.

In most implementations, the flow looks like this:

Agent plans an action
User is shown a confirmation prompt
User taps confirm
Action dispatches

The assumption is that step 3 leads directly to step 4. But in practice, there’s a gap — and things can happen in that gap.

This post covers what we call the late confirmation race in StareBrain, and how we handle it without introducing false blocks or silent duplicates.

What Can Go Wrong in the Gap

The most common case: the action was already dispatched by an earlier path before the confirmation came back.

How does that happen? A few ways:

The user confirmed on one device/session while a background task had already triggered the same action
A retry fired because the first dispatch timed out, but the timeout was too aggressive — the original dispatch was still in-flight
The auto-confirm threshold was met (for low-risk actions) at the same time the manual confirm came back

In all three cases, a naive implementation dispatches twice. One dispatch was right. The other is a duplicate.

Checking Terminal State Before Replacement Dispatch

The fix is straightforward: before honoring a confirmation by dispatching, check whether the action is already in a terminal delivery state.

`sealed class ConfirmationOutcome {
    data class Dispatched(val actionId: String) : ConfirmationOutcome()
    data class AlreadyCompleted(val actionId: String, val state: DeliveryState) : ConfirmationOutcome()
    data class Superseded(val actionId: String) : ConfirmationOutcome()
    data class Blocked(val actionId: String, val reason: String) : ConfirmationOutcome()
}

class ConfirmationHandler(
    private val actionRepository: ActionRepository,
    private val dispatcher: ActionDispatcher
) {
    fun handleConfirmation(actionId: String): ConfirmationOutcome {
        val record = actionRepository.find(actionId)
            ?: return ConfirmationOutcome.Blocked(actionId, "action record not found")

        // Terminal check before dispatch
        return when (record.delivery) {
            DeliveryState.CONFIRMED -> {
                ConfirmationOutcome.AlreadyCompleted(actionId, DeliveryState.CONFIRMED)
            }
            DeliveryState.FAILED -> {
                ConfirmationOutcome.AlreadyCompleted(actionId, DeliveryState.FAILED)
            }
            DeliveryState.PENDING -> {
                // Safe to dispatch — not yet in a terminal state
                dispatcher.dispatch(record)
                ConfirmationOutcome.Dispatched(actionId)
            }
        }
    }
}`

If the delivery state is already CONFIRMED or FAILED, the confirmation is honored as a no-op. The user’s tap is acknowledged, but no second dispatch fires.

The DENIED_UNRESOLVED Case

The terminal check above handles CONFIRMED and FAILED cleanly. The harder case is DENIED_UNRESOLVED — the action dispatched, but the outcome is unknown.

This is not a terminal state in the sense that it’s resolved, but it is a state where a replacement dispatch is dangerous: if the first dispatch actually landed on the provider side and just failed to confirm back, a second dispatch is a duplicate.

`fun handleConfirmation(actionId: String): ConfirmationOutcome {
    val record = actionRepository.find(actionId)
        ?: return ConfirmationOutcome.Blocked(actionId, "action record not found")

    return when {
        record.delivery == DeliveryState.CONFIRMED ->
            ConfirmationOutcome.AlreadyCompleted(actionId, DeliveryState.CONFIRMED)

        record.delivery == DeliveryState.FAILED ->
            ConfirmationOutcome.AlreadyCompleted(actionId, DeliveryState.FAILED)

        record.actionStatus == ActionStatus.DENIED_UNRESOLVED -> {
            // Do NOT dispatch. Surface for reconciliation first.
            ConfirmationOutcome.Blocked(
                actionId,
                "prior dispatch unresolved — reconcile before retry"
            )
        }

        record.delivery == DeliveryState.PENDING ->
            dispatcher.dispatch(record).let {
                ConfirmationOutcome.Dispatched(actionId)
            }

        else -> ConfirmationOutcome.Blocked(actionId, "unexpected state")
    }
}`

The DENIED_UNRESOLVED case blocks replacement dispatch and routes to reconciliation. The user sees that the previous attempt’s outcome is unknown and needs to be checked before proceeding — not a silent failure, not a silent retry.

Idempotency on the Dispatch Side

The terminal check on confirmation prevents duplicate dispatches from the confirmation handler. But the dispatch path itself should also be idempotent, because the confirmation handler isn’t the only entry point.

`class ActionDispatcher(
    private val repository: ActionRepository,
    private val provider: ActionProvider
) {
    fun dispatch(record: ActionRecord): DispatchResult {
        // Idempotency key scoped to action + attempt number
        val idempotencyKey = "${record.actionId}:${record.attemptNumber}"

        // Re-check delivery state inside dispatch — the terminal check
        // in ConfirmationHandler is a fast path, not the only guard
        if (record.delivery != DeliveryState.PENDING) {
            return DispatchResult.Skipped(record.actionId, "non-pending state at dispatch")
        }

        return try {
            val result = provider.execute(record, idempotencyKey)
            repository.markDelivered(record.actionId, result.providerObjectId)
            DispatchResult.Succeeded(record.actionId)
        } catch (e: TimeoutException) {
            repository.markUnresolved(record.actionId)
            DispatchResult.Unresolved(record.actionId)
        } catch (e: Exception) {
            repository.markFailed(record.actionId)
            DispatchResult.Failed(record.actionId, e.message)
        }
    }
}

sealed class DispatchResult {
    data class Succeeded(val actionId: String) : DispatchResult()
    data class Failed(val actionId: String, val reason: String?) : DispatchResult()
    data class Unresolved(val actionId: String) : DispatchResult()
    data class Skipped(val actionId: String, val reason: String) : DispatchResult()
}`

The idempotency key scoped to actionId + attemptNumber means a retry on the same attempt doesn’t produce a second provider-side effect. A new attempt gets a new key.

What the User Sees

The goal is that the user never sees a duplicate action and never gets a silent failure. What they see instead:

Normal path: confirm → action runs → done
Already completed: confirm acknowledged, brief notice that it already ran
DENIED_UNRESOLVED: confirm blocked, clear message that the previous attempt’s outcome is unknown and needs to be checked

The third case is the uncomfortable one to surface. But a user who sees “we’re not sure if the last attempt ran” is in a better position than a user who just had a duplicate booking made silently.

What This Closes

The late confirmation race is a narrow window but it’s a real one — especially in mobile contexts where network conditions vary and the same action can be triggered from multiple paths. The terminal check before dispatch, combined with idempotent dispatch, closes both the happy-path duplicate and the unresolved-state duplicate without adding meaningful latency to the normal flow.

Context Propagation in Android AI Agents: Resolving Device State Before Action Dispatch

StareBrain — Fri, 23 Oct 2026 03:30:01 +0000

An AI agent on a phone has access to something a server-side agent doesn’t: the device itself. Calendar events, saved locations, recent contacts, active notifications — all of it is locally available before any network call is made.

The question isn’t whether to use that context. It’s how to resolve it into action parameters without asking the user for information the phone already has, and without silently filling in details the phone only partially knows.

This post covers the context propagation layer in StareBrain — how device state gets resolved into action parameters, how confidence thresholds decide when to auto-fill vs. suggest vs. ask, and what happens when resolution fails.

The Resolution Problem

When a user says “book a slot for my dentist appointment,” the agent needs to resolve:

Which calendar? (probably the default one)
Which slot? (depends on availability)
Which location? (saved as “dentist” in the location store, or needs to be asked)
Which contact to notify, if any? (ambiguous without more context)

Some of these can be resolved from device state with high confidence. Others can be suggested. Others need to be asked explicitly. Collapsing all of them into a single “ask the user for everything” flow is safe but slow. Auto-filling everything without surfacing uncertainty is fast but fragile.

The resolution layer sits between intent parsing and action dispatch, and its job is to decide which parameters fall into which bucket.

Modeling Device Context

`data class DeviceContext(
    val upcomingEvents: List<CalendarEvent>,
    val savedLocations: List<SavedLocation>,
    val recentContacts: List<Contact>,
    val recentApps: List<String>,
    val activeNotifications: List<NotificationSummary>
)

data class CalendarEvent(
    val eventId: String,
    val title: String,
    val startTime: Instant,
    val location: String?,
    val attendees: List<String>
)

data class SavedLocation(
    val label: String,
    val address: String,
    val coordinates: Pair<Double, Double>
)`

The context is captured at intent-parse time — a snapshot of device state at the moment the user expressed the intent. This matters: if resolution runs against live state at dispatch time, a contact added or an event modified after the user spoke could produce parameters the user never approved.

Confidence-Gated Resolution

Each parameter resolution produces a confidence level that determines what happens next:

`enum class ResolutionConfidence { HIGH, MEDIUM, LOW, UNRESOLVABLE }

data class ParameterValue(
    val value: Any?,
    val confidence: ResolutionConfidence,
    val source: ContextSource
)

sealed class ContextSource {
    object DeviceCalendar : ContextSource()
    object SavedLocations : ContextSource()
    object RecentContacts : ContextSource()
    object UserProvided : ContextSource()
    object Inferred : ContextSource()
}

fun ParameterValue.shouldAutoFill(): Boolean =
    confidence == ResolutionConfidence.HIGH

fun ParameterValue.shouldSuggest(): Boolean =
    confidence == ResolutionConfidence.MEDIUM

fun ParameterValue.shouldAsk(): Boolean =
    confidence == ResolutionConfidence.LOW ||
    confidence == ResolutionConfidence.UNRESOLVABLE`

HIGH → auto-fill silently. The device has this unambiguously (default calendar, a location saved under an exact label match).

MEDIUM → surface as a suggestion. The device has a candidate but it’s not certain (a location match on partial label, a contact with a common name).

LOW / UNRESOLVABLE → ask the user explicitly before proceeding.

The Resolver

`class ContextResolver(
    private val calendarProvider: CalendarProvider,
    private val locationStore: LocationStore,
    private val contactStore: ContactStore
) {
    fun resolve(
        intent: ActionIntent,
        context: DeviceContext
    ): Map<String, ParameterValue> {
        return intent.requiredParameters.associate { param ->
            param.name to resolveParameter(param, context)
        }
    }

    private fun resolveParameter(
        param: Parameter,
        context: DeviceContext
    ): ParameterValue {
        return when (param) {
            is Parameter.Location -> resolveLocation(param, context)
            is Parameter.Contact -> resolveContact(param, context)
            is Parameter.TimeSlot -> resolveTimeSlot(param, context)
            is Parameter.Calendar -> resolveCalendar(param, context)
        }
    }

    private fun resolveLocation(
        param: Parameter.Location,
        context: DeviceContext
    ): ParameterValue {
        val exactMatch = context.savedLocations
            .firstOrNull { it.label.equals(param.hint, ignoreCase = true) }

        if (exactMatch != null) {
            return ParameterValue(
                value = exactMatch,
                confidence = ResolutionConfidence.HIGH,
                source = ContextSource.SavedLocations
            )
        }

        val partialMatch = context.savedLocations
            .firstOrNull { it.label.contains(param.hint, ignoreCase = true) }

        if (partialMatch != null) {
            return ParameterValue(
                value = partialMatch,
                confidence = ResolutionConfidence.MEDIUM,
                source = ContextSource.SavedLocations
            )
        }

        return ParameterValue(
            value = null,
            confidence = ResolutionConfidence.UNRESOLVABLE,
            source = ContextSource.SavedLocations
        )
    }
}`

Building the Agent Context

The resolved parameters get packaged into an AgentContext that travels with the action through to dispatch:

`data class AgentContext(
    val actionIntent: ActionIntent,
    val deviceContext: DeviceContext,
    val resolvedParameters: Map<String, ParameterValue>,
    val capturedAt: Instant
)

fun AgentContext.pendingParameters(): List<String> {
    return resolvedParameters
        .filter { (_, value) -> value.shouldAsk() }
        .map { (name, _) -> name }
}

fun AgentContext.suggestedParameters(): Map<String, ParameterValue> {
    return resolvedParameters
        .filter { (_, value) -> value.shouldSuggest() }
}

fun AgentContext.autoFilledParameters(): Map<String, Any?> {
    return resolvedParameters
        .filter { (_, value) -> value.shouldAutoFill() }
        .mapValues { (_, value) -> value.value }
}`

Before the action proceeds to the confirmation step, the agent checks pendingParameters(). If anything is unresolvable, the user is asked. If there are suggestions, they’re surfaced with the option to confirm or override. Only HIGH confidence parameters skip the user entirely.

Why capturedAt Matters

The capturedAt timestamp on AgentContext is the snapshot boundary. Resolution runs once, against the device state at intent time. If the user takes three minutes to confirm the action, the context doesn’t re-resolve — the parameters they’re approving are the ones they were shown.

This is intentional. Re-resolving at confirmation time could change the suggested contact or location between when the user read the suggestion and when they tapped confirm, which is a different version of the stale-plan problem at the resolution layer rather than the dispatch layer.

The resolution snapshot is the contract. The dispatch layer’s job (covered in earlier posts) is to verify that the external world still matches that contract at execution time.

What This Gives You

The resolver separates three categories of knowledge: what the device knows for certain, what it can reasonably guess, and what it genuinely doesn’t have. Surfacing that distinction explicitly — rather than flattening it into “fill what you can and ask for the rest” — keeps the user in the loop on the decisions that affect them and out of the loop on the ones that don’t.

Why AI Agents Need a Reconciliation Layer: Modeling the Gap Between Dispatch and Confirmation

StareBrain — Thu, 22 Oct 2026 03:35:41 +0000

When an AI agent dispatches an action — booking a slot, sending a message, writing a file — there are two questions that need answering, and they’re not the same question:

Did the action reach the provider?
Did the provider accept it?

Most agent implementations collapse these into one. The action fires, something comes back, and the outcome is recorded as success or failure. That works until the network gets involved, the provider is slow, or the response never arrives.

This post covers the reconciliation layer we built in StareBrain to handle the gap between dispatch and confirmation — and why collapsing those two questions into one creates failure modes that are invisible until they’re not.

The Two-Axis State Model

Every dispatchable action has two independent state progressions:

`enum class DeliveryState { PENDING, CONFIRMED, FAILED }
enum class AcceptanceState { PENDING, ACCEPTED, REJECTED }`

DeliveryState tracks whether the action reached the provider. AcceptanceState tracks whether the provider acted on it. These are orthogonal — delivery can be confirmed while acceptance is still pending, and acceptance can never move out of PENDING until delivery is CONFIRMED.

`data class ActionRecord(
    val actionId: String,
    val dispatchId: String,
    val providerObjectId: String?,
    val delivery: DeliveryState,
    val acceptance: AcceptanceState,
    val dispatchedAt: Instant,
    val confirmedAt: Instant?,
    val eligibleForReconciliationAt: Instant
)

fun ActionRecord.tryAccept(verdict: AcceptanceState): ActionRecord {
    check(delivery == DeliveryState.CONFIRMED) {
        "Cannot evaluate acceptance before delivery is confirmed."
    }
    return copy(acceptance = verdict)
}`

The structural invariant — acceptance cannot move until delivery is confirmed — prevents a class of race conditions where an optimistic acceptance gets recorded before the provider has even received the request.

DENIED_UNRESOLVED: A First-Class Outcome

The failure mode most systems miss: the action dispatched, the provider was reached, but the outcome is unknown. Network timeout after dispatch. Provider returned a non-terminal status. Response arrived but was malformed.

This isn’t a failure. It isn’t a success. It’s an unresolvable state — and it needs to stay that way permanently.

`enum class ActionStatus { CONFIRMED, FAILED, DENIED_UNRESOLVED }`

DENIED_UNRESOLVED never decays into success on timeout. It never gets silently retried. It sits in the record as a permanent signal that this action’s outcome is unknown and requires explicit reconciliation before any replacement dispatch.

The reason this matters: if a booking dispatch returned DENIED_UNRESOLVED and the agent silently retries, the provider may have already processed the first request. The result is a duplicate booking the user never approved.

Provider Capability Tiers

Not every provider supports the same reconciliation capabilities. We model this explicitly:

`enum class ProviderCapabilityTier {
    FULL,           // Native webhook + queryable by our reference
    RECONCILABLE,   // No webhook, but queryable by client reference
    PARTIAL,        // Queryable by provider ID only (we must store their ID)
    BLIND           // No query capability — outcome unknowable after dispatch
}`

The tier determines what reconciliation is possible after a DENIED_UNRESOLVED:

FULL: reconcile via webhook or active query using our own reference
RECONCILABLE: requires that our client reference was transmitted in the request AND is queryable by the provider — both conditions must hold
PARTIAL: we can query, but only if we captured the provider’s object ID at dispatch time
BLIND: reconciliation is impossible — surface to user for manual resolution

`data class ReconciliationPolicy(
    val tier: ProviderCapabilityTier,
    val minAgeBeforeEligible: Duration,
    val maxAttempts: Int,
    val clientReferenceKey: String?
)

fun ActionRecord.isEligibleForReconciliation(): Boolean {
    return Instant.now().isAfter(eligibleForReconciliationAt)
}`

The minAgeBeforeEligible gate prevents reconciliation attempts against records that are still within the provider’s normal processing window — querying too early produces false negatives.

The Pre-Dispatch Reconciliation Key

For RECONCILABLE and FULL tiers, the client reference must be generated before dispatch — not after. If it’s generated after, a network failure between generation and transmission means we have a reference that doesn’t match anything on the provider side.

`data class DispatchContext(
    val actionId: String,
    val reconciliationKey: String,  // generated before dispatch
    val providerTier: ProviderCapabilityTier,
    val dispatchedAt: Instant
)

fun buildDispatchContext(actionId: String, tier: ProviderCapabilityTier): DispatchContext {
    return DispatchContext(
        actionId = actionId,
        reconciliationKey = UUID.randomUUID().toString(),
        providerTier = tier,
        dispatchedAt = Instant.now()
    )
}`

The key is stored locally before the network call. If the call fails before transmitting the key, the record is DENIED_UNRESOLVED with no matching provider-side reference — which is the correct state, because reconciliation by reference isn’t possible.

Idempotency Scoping

Retries on non-terminal states need idempotency keys to prevent duplicate execution. We scope the key to event ID + action type, not just event ID:

`fun buildIdempotencyKey(eventId: String, actionType: String): String {
    return "$eventId:$actionType"
}`

Scoping to event ID alone fails when the same event produces multiple actions of different types — the second action gets rejected as a duplicate of the first. Scoping to event ID + action type keeps retries safe without blocking legitimate parallel actions.

What This Closes

The two-axis model makes it impossible to record acceptance before delivery is confirmed. DENIED_UNRESOLVED as a permanent state prevents silent retry on unknown outcomes. Provider capability tiers make reconciliation strategy explicit at the architectural level rather than scattered across action handlers. Pre-dispatch key generation closes the reference mismatch on network failure.

The invisible failure mode — action dispatched, outcome unknown, agent moves on — becomes a named, queryable, reconcilable state.

Stale-Plan Protection in Android Action Execution: How We Closed the Confirm-to-Dispatch Gap

StareBrain — Wed, 21 Oct 2026 03:49:41 +0000

When a user confirms an action in an AI agent, they’re approving a plan built from a snapshot of the world at that moment. By the time the action dispatches — even seconds later — that snapshot may no longer be valid.

We call this the stale-plan problem. It’s distinct from stale data (a UI showing old info) and distinct from execution failure (the action tried and errored). It’s the gap between confirmed and still valid at dispatch time.

Here’s how we structured the protection layer in StareBrain.

The Two Moments That Matter

Most action pipelines treat confirmation as the green light. We split it into two checkpoints:

Confirmation time — user approves the plan built from current evidence
Dispatch time — action fires against live state

The dependency check happens at dispatch time, not confirmation time. If evidence has changed in a way that affects the approved intent, the action blocks before any side effect occurs.

Modeling the Evidence Dependency

Every dispatchable action declares which fields it depends on:

`data class EvidenceDependency(
    val sourceId: String,
    val fingerprint: String,
    val capturedAt: Instant,
    val fields: List<String>
)

data class ActionPlan(
    val actionId: String,
    val intent: String,
    val steps: List<PlannedStep>,
    val evidenceDependencies: List<EvidenceDependency>,
    val estimatedSideEffects: List<SideEffect>,
    val requiresConfirmation: Boolean
)`

The fingerprint is computed at confirmation time over only the fields that affect intent — not the whole record. This matters: an unrelated field changing in the source record shouldn’t invalidate a valid plan.

The Pre-Dispatch Validator

Before any step with side effects executes, we revalidate each dependency:

`sealed class DependencyCheckResult {
    object Valid : DependencyCheckResult()
    data class Stale(
        val sourceId: String,
        val changedFields: List<String>,
        val capturedFingerprint: String,
        val currentFingerprint: String
    ) : DependencyCheckResult()
    data class Unresolvable(val sourceId: String, val reason: String) : DependencyCheckResult()
}

class PreDispatchValidator(
    private val evidenceStore: EvidenceStore
) {
    fun validate(plan: ActionPlan): List<DependencyCheckResult> {
        return plan.evidenceDependencies.map { dep ->
            val current = evidenceStore.fingerprintNow(dep.sourceId, dep.fields)
                ?: return@map DependencyCheckResult.Unresolvable(dep.sourceId, "source not found")

            if (current == dep.fingerprint) {
                DependencyCheckResult.Valid
            } else {
                DependencyCheckResult.Stale(
                    sourceId = dep.sourceId,
                    changedFields = evidenceStore.diffFields(dep.sourceId, dep.fingerprint, current),
                    capturedFingerprint = dep.fingerprint,
                    currentFingerprint = current
                )
            }
        }
    }
}`

Fail-Closed by Default

If any dependency comes back Stale or Unresolvable, we block before execution and surface a structured result:

`sealed class DispatchOutcome {
    data class Executed(val actionId: String, val completedAt: Instant) : DispatchOutcome()
    data class BlockedStale(
        val actionId: String,
        val staleDependencies: List<DependencyCheckResult.Stale>
    ) : DispatchOutcome()
    data class BlockedUnresolvable(
        val actionId: String,
        val reason: String
    ) : DispatchOutcome()
}

class ActionDispatcher(
    private val validator: PreDispatchValidator,
    private val executor: StepExecutor
) {
    fun dispatch(plan: ActionPlan): DispatchOutcome {
        val results = validator.validate(plan)

        val stale = results.filterIsInstance<DependencyCheckResult.Stale>()
        val unresolvable = results.filterIsInstance<DependencyCheckResult.Unresolvable>()

        if (stale.isNotEmpty()) {
            return DispatchOutcome.BlockedStale(plan.actionId, stale)
        }

        if (unresolvable.isNotEmpty()) {
            return DispatchOutcome.BlockedUnresolvable(
                plan.actionId,
                unresolvable.first().reason
            )
        }

        executor.execute(plan.steps)
        return DispatchOutcome.Executed(plan.actionId, Instant.now())
    }
}`

No side effects run if the plan is stale. The block is logged, the user gets a fresh confirmation prompt with updated state, and the original plan is discarded.

Why Field-Level Fingerprinting

Hashing the whole source record is simpler but creates false invalidations. For a calendar slot:

slot_id and status affect intent — if either changes, the plan is stale
last_modified_by or color_label are irrelevant — changing them shouldn’t block a booking

Field-level fingerprinting keeps the protection tight and avoids prompting users to re-confirm actions that are still semantically valid.

`fun fingerprintFields(record: Map<String, Any?>, fields: List<String>): String {
    val relevant = fields.sorted().associateWith { record[it] }
    return MessageDigest.getInstance("SHA-256")
        .digest(relevant.toString().toByteArray())
        .joinToString("") { "%02x".format(it) }
        .take(16)
}
`

What This Closes

The confirm-to-dispatch gap is small in time but large in consequence for actions that write state — calendar bookings, messages, file writes. This layer closes it without changing the user-facing confirmation flow: the extra check is invisible unless something actually changed.

The observable behavior: protected path blocks with zero side effects when evidence is stale. Unprotected path executes regardless. That comparison is the test.

How we built a dry-run mode for on-device agent actions

StareBrain — Tue, 20 Oct 2026 04:33:57 +0000

One of the hardest trust problems in an AI agent isn’t getting the action right. It’s convincing the user it’s going to get the action right before it runs.

StareBrain operates on a user’s phone — real apps, real data, actions that can’t always be undone. Booking a cab, sending a message, setting a reminder. The agent needs to earn the user’s confidence on every action, not just the first time.

The way we approached this: every action goes through a dry-run pass before it executes. The agent builds a full action plan, estimates the side effects, and presents a human-readable summary for confirmation. Only after the user approves does the real execution begin.

Here’s how that works in code.

The action plan

Before any execution, the planner produces an ActionPlan — a complete description of what the agent intends to do:

`data class ActionPlan(
    val actionId: String,
    val intent: String,
    val steps: List<PlannedStep>,
    val estimatedSideEffects: List<SideEffect>,
    val requiresConfirmation: Boolean
)

data class PlannedStep(
    val stepId: String,
    val appTarget: String,
    val operation: String,
    val parameters: Map<String, String>,
    val isReversible: Boolean
)

sealed class SideEffect {
    data class DataWrite(val app: String, val description: String) : SideEffect()
    data class NetworkRequest(val destination: String, val description: String) : SideEffect()
    data class Notification(val description: String) : SideEffect()
    object NoSideEffect : SideEffect()
}`

The plan is built entirely from the intent and the resolved device context — no app is opened, no tap is made. It’s a description of what would happen, not what is happening.

Dry-run execution

The dry-run pass walks every step in the plan and validates it without executing:

`class DryRunExecutor(
    private val appRegistry: InstalledAppRegistry,
    private val permissionChecker: PermissionChecker
) {
    fun validate(plan: ActionPlan): DryRunResult {
        val stepResults = plan.steps.map { step ->
            validateStep(step)
        }

        return DryRunResult(
            planId = plan.actionId,
            stepResults = stepResults,
            isExecutable = stepResults.all { it.canExecute },
            blockers = stepResults.flatMap { it.blockers }
        )
    }

    private fun validateStep(step: PlannedStep): StepValidation {
        val appInstalled = appRegistry.isInstalled(step.appTarget)
        val hasPermission = permissionChecker.hasRequired(step.operation)

        val blockers = buildList {
            if (!appInstalled) add(Blocker.AppNotInstalled(step.appTarget))
            if (!hasPermission) add(Blocker.PermissionMissing(step.operation))
        }

        return StepValidation(
            stepId = step.stepId,
            canExecute = blockers.isEmpty(),
            blockers = blockers
        )
    }
}

data class DryRunResult(
    val planId: String,
    val stepResults: List<StepValidation>,
    val isExecutable: Boolean,
    val blockers: List<Blocker>
)

sealed class Blocker {
    data class AppNotInstalled(val appName: String) : Blocker()
    data class PermissionMissing(val permission: String) : Blocker()
    data class ParameterUnresolved(val paramName: String) : Blocker()
}`

If the dry run finds blockers, the agent surfaces them before asking for confirmation — not after attempting execution and failing.

The confirmation surface

The dry-run result feeds directly into the confirmation UI. The user sees a plain-language summary of what’s about to happen:

`fun ActionPlan.toConfirmationSummary(): ConfirmationSummary {
    return ConfirmationSummary(
        title = intent,
        steps = steps.map { step ->
            "${step.appTarget}: ${step.operation} " +
            step.parameters.entries.joinToString(", ") { "${it.key} = ${it.value}" }
        },
        sideEffects = estimatedSideEffects
            .filterNot { it is SideEffect.NoSideEffect }
            .map { it.toHumanReadable() },
        hasIrreversibleSteps = steps.any { !it.isReversible }
    )
}

data class ConfirmationSummary(
    val title: String,
    val steps: List<String>,
    val sideEffects: List<String>,
    val hasIrreversibleSteps: Boolean
)`

If any step is irreversible, the confirmation dialog uses stronger language and requires an explicit tap — not just a dismiss. A booking can’t be unbooked automatically. A sent message can’t be unsent. The user should know that before they confirm.

Why dry-run before confirm, not confirm before dry-run

The tempting shortcut is to ask for confirmation first, then validate. It’s simpler to implement.

The problem: if validation fails after confirmation, you’ve already set an expectation you can’t fulfill. The user said yes, and then the agent came back with “actually, the app isn’t installed.” That’s a worse experience than not asking yet.

Dry-run first means the confirmation is always about a plan the agent knows it can execute. The “yes” is to something real, not to a plan that might fail on step two.

The gap this closes

On-device agents earn trust by being predictable. The user doesn’t need the agent to be perfect — they need to know what it’s about to do before it does it, and to have a moment to say no.

Dry-run mode is how we make that moment meaningful. Not a generic “the agent will now perform actions on your behalf” disclaimer, but a specific, checkable list of exactly what’s going to happen.

If the user can read the plan and say “yes, that’s what I meant” — that’s the confirmation worth having.

How we handle “the phone already knows this” — context propagation in an on-device AI agent

StareBrain — Mon, 19 Oct 2026 03:59:33 +0000

One of the most common reactions we get from StareBrain beta users is some version of: “why do I still have to tell it things it should already know?”

It’s a fair question. The phone has the calendar. It has the contacts. It has the location history, the saved addresses, the flight confirmation in the email. The information exists. The problem is that each app owns its slice of it and nothing connects the dots automatically.

Building an on-device AI agent means solving that problem — not by sending everything to a cloud service, but by building a context layer that runs locally and propagates the right information to the right action at the right time.

Here’s how we approached it.

The problem: action context vs device context

When a user says “book me a cab for my usual airport,” there are two kinds of context the agent needs:

Action context: what action is being requested, what parameters it needs, what apps can fulfill it
Device context: what does the phone already know that’s relevant — upcoming calendar events, saved locations, recent searches

Most agent architectures handle action context well. Device context is where things get complicated, because it’s distributed across the OS and multiple apps, each with their own permission model.

`data class AgentContext(
    val actionIntent: ActionIntent,
    val deviceContext: DeviceContext,
    val resolvedParameters: Map<String, Any>
)

data class DeviceContext(
    val upcomingEvents: List<CalendarEvent>,
    val savedLocations: List<SavedLocation>,
    val recentApps: List<String>,
    val activeNotifications: List<NotificationSummary>
)`

The agent needs to resolve parameters from device context before dispatch — not during, and not by asking the user for information the phone already has.

Context resolution before dispatch

We added a resolution pass that runs before any action is dispatched. It takes the raw intent and tries to fill in missing parameters from device context before surfacing anything to the user:

`class ContextResolver(
    private val calendarProvider: CalendarProvider,
    private val locationStore: LocationStore
) {
    fun resolve(intent: ActionIntent, context: DeviceContext): ResolvedIntent {
        val params = intent.requiredParameters.associateWith { param ->
            when (param) {
                is Parameter.Location -> resolveLocation(param, context)
                is Parameter.DateTime -> resolveDateTime(param, context)
                is Parameter.Contact -> resolveContact(param, context)
                else -> UnresolvedParameter(param)
            }
        }
        return ResolvedIntent(intent, params)
    }

    private fun resolveLocation(
        param: Parameter.Location,
        context: DeviceContext
    ): ParameterValue {
        // "usual airport" → check saved locations for airport category
        val saved = context.savedLocations
            .filter { it.category == param.hint }
            .maxByOrNull { it.useCount }
        return saved?.let { ParameterValue.Resolved(it.address) }
            ?: ParameterValue.NeedsConfirmation(param)
    }
}`

If a parameter can be resolved confidently, it’s filled in automatically. If it can be resolved with reasonable confidence but not certainty, it’s surfaced to the user as a pre-filled suggestion they can confirm or change. If it can’t be resolved at all, it’s flagged as missing and the user is asked.

The key rule: never ask for information the phone already has.

Confidence thresholds

Not all resolutions are equal. “Your usual airport” from a saved location you’ve used 40 times is high confidence. “Your usual airport” inferred from one calendar event three months ago is low confidence.

`enum class ResolutionConfidence { HIGH, MEDIUM, LOW, UNRESOLVABLE }

data class ParameterValue(
    val value: Any?,
    val confidence: ResolutionConfidence,
    val source: ContextSource
)

fun ParameterValue.shouldAutoFill(): Boolean =
    confidence == ResolutionConfidence.HIGH

fun ParameterValue.shouldSuggest(): Boolean =
    confidence == ResolutionConfidence.MEDIUM

fun ParameterValue.shouldAsk(): Boolean =
    confidence == ResolutionConfidence.LOW || confidence == ResolutionConfidence.UNRESOLVABLE
`

High confidence → auto-fill, show in confirmation summary.
Medium confidence → pre-fill with a “is this right?” prompt.
Low confidence → ask the user directly.

This keeps the agent from confidently doing the wrong thing while still reducing the number of things the user has to say.

The privacy constraint

Everything in this system runs on-device. No context leaves the phone. That’s a hard constraint, not a preference.

The practical implication: we can’t use a cloud model to reason over the full device context, because we can’t send the full device context to a cloud model. The resolution logic has to be deterministic enough to run locally, which means it needs to be explicit about what signals it uses and how it weighs them.

That’s a tighter constraint than cloud-based approaches, but it’s what makes the privacy guarantee credible. “Your data never leaves your phone” only means something if the architecture actually enforces it.

What this solves (and doesn’t)

Context resolution handles the “it should already know this” problem for structured data — saved locations, calendar events, contacts. It doesn’t solve open-ended inference (“what would I usually do here?”) or cross-app state that requires active reading of app content.

Those are harder problems. The structured data layer is the foundation. Getting it right first means users stop being asked for things the phone already has, which is the baseline expectation before anything more ambitious makes sense.

The goal isn’t to build the most capable agent. It’s to build one that never makes you feel like you’re talking to something that doesn’t know you.

The question that kills bad product assumptions before you build them

StareBrain — Sun, 18 Oct 2026 04:02:26 +0000

Most bad product decisions don’t happen in code review. They happen in the assumptions that never got questioned before anyone wrote a line.

We’ve been building StareBrain — an on-device AI agent for Android — for long enough now to have made a few of those assumptions and paid for them. The one that cost the most time wasn’t a technical decision. It was a research question we asked wrong.

The wrong question

Early on, we asked potential users: “Would you use an AI agent that could control your phone for you?”

Almost everyone said yes.

That answer told us almost nothing useful.

“Would you use” is a hypothetical. It costs the person nothing to say yes. It requires no memory, no specificity, no commitment. It’s the lowest-friction possible signal, which means it’s also the least meaningful.

We had a lot of yeses. We had no idea whether we had a real problem.

The question that changed our research

The shift came when we started asking: “Walk me through the last time you had to do something on your phone that felt like it should have been automatic.”

That question:

Forces a real memory, not a hypothetical
Surfaces the actual friction, not the imagined one
Shows you the workaround they’re already using
Reveals whether the problem happens often enough to matter

The answers were specific in a way the first question never produced. People described the exact sequence of steps — open this app, copy this, go back, paste here, navigate to this screen, re-enter this information that the phone already knows. The friction wasn’t abstract. It was a particular four-app chain they’d done so many times they’d stopped noticing it was annoying.

That’s the kind of answer you can build from.

The follow-up that filters even further

After the story question, we added one more: “Have you ever paid for anything to make this easier, or spent real time trying to fix it?”

`// This is what we're trying to eliminate:
// User intent: "book a cab to the airport"
// Current reality:
fun userDoesManually() {
    openApp("Maps")
    searchFor("airport terminal")
    copyAddress()
    openApp("CabApp")
    pasteAddress()
    checkCalendarForFlightTime()
    switchBackToCabApp()
    confirmBooking()
}

// What StareBrain handles:
fun agentHandles(intent: String) {
    val plan = planner.decompose(intent)
    plan.steps.forEach { step ->
        dispatcher.execute(step, requiresConfirmation = step.hasIrreversibleSideEffect)
    }
}`

If someone has spent real time or money trying to solve this — searched for an app, tried a shortcut, paid for a tool — that’s a confirmed problem. They already voted with behavior.

If they said “yeah that’s annoying” but never tried to fix it, the pain might not be sharp enough to drive adoption. That’s useful to know before you build.

What this changed in practice

We stopped validating features with “would you use this?” entirely. Every research conversation now starts with a story prompt and ends with a spending or effort question.

The story prompt tells you the problem is real. The spending question tells you the problem is worth solving.

Between those two, you can filter out a huge amount of building-for-an-imaginary-user before you ever open Android Studio.

The code is the easy part. Getting the question right is what makes it worth writing.

Why we stopped retrying on timeout and built reconciliation instead

StareBrain — Sat, 17 Oct 2026 04:11:54 +0000

Early in StareBrain’s action dispatch layer, we had a simple rule: if an action times out, retry it.

It felt safe. It felt standard. It was wrong.

The problem isn’t the retry. The problem is what a timeout actually tells you — which is almost nothing.

What a timeout means (and doesn’t mean)

When a dispatch call times out, you know one thing: you didn’t get a response in time. That’s it. You don’t know whether the action reached the provider. You don’t know whether it executed. You don’t know whether it’s sitting in a queue about to execute in the next 200ms.

Retrying in that state doesn’t solve the ambiguity. It doubles it. Now you have two dispatches in flight and still no confirmed outcome for either.

For a calendar booking, that means two bookings. For a payment, two charges. For a message send, two messages. The user asked for one thing.

So we stopped treating timeout as a signal to retry and started treating it as a signal to reconcile.

The state model underneath

We track every action on two independent axes:

`enum class DeliveryState { PENDING, CONFIRMED, FAILED }
enum class AcceptanceState { PENDING, ACCEPTED, REJECTED }

data class ActionRecord(
    val actionId: String,
    val dispatchId: String,
    val providerObjectId: String?,
    val delivery: DeliveryState,
    val acceptance: AcceptanceState,
    val dispatchedAt: Instant,
    val confirmedAt: Instant?,
    val eligibleForReconciliationAt: Instant
)`

Delivery tracks whether the action reached the provider and got a response. Acceptance tracks whether the provider processed it correctly.

These are orthogonal. A delivery can be confirmed (provider responded) while acceptance is still pending (provider is async and hasn’t evaluated it yet). Acceptance cannot move out of PENDING until delivery is CONFIRMED — that’s a structural invariant enforced in code:

`fun ActionRecord.tryAccept(verdict: AcceptanceState): ActionRecord {
    check(delivery == DeliveryState.CONFIRMED) {
        "Cannot evaluate acceptance before delivery is confirmed."
    }
    return copy(acceptance = verdict)
}`

A timeout leaves delivery in PENDING. That record is not a failure — it’s unresolved. We give it a permanent status to match:

`enum class ActionStatus {
    CONFIRMED,
    FAILED,
    DENIED_UNRESOLVED
}`

DENIED_UNRESOLVED means: the action was not confirmed, and we cannot establish what happened programmatically. It never decays into success on timeout. It stays unresolved until a human review or a successful reconciliation pass clears it.

The consistency window

One subtlety: “not found” after a timeout doesn’t mean “didn’t happen.” Some providers have replication lag. A record written during a slow dispatch might not be queryable for several seconds after the call returns.

We gate reconciliation behind a minimum age:

`fun ActionRecord.isEligibleForReconciliation(): Boolean {
    return Instant.now().isAfter(eligibleForReconciliationAt)
}`

eligibleForReconciliationAt is set at dispatch time: dispatchedAt + consistencyWindowDuration. A reconciliation job that runs before this gate doesn’t query the provider — it waits. “Not found inside the window” is not a failure signal.

Provider capability tiers

Not every provider supports the same query surface, which changes what reconciliation is possible:

`enum class ProviderCapabilityTier { FULL, RECONCILABLE, PARTIAL, BLIND }`

FULL: provider returns an artifact ID, supports idempotency keys, and has a query endpoint. Full reconciliation possible.
RECONCILABLE: provider returns an artifact ID and has a query endpoint, but no idempotency key support. Reconciliation possible, but a clean timeout without a returned artifact ID leaves no anchor to query against — the client reference must be transmitted in the dispatch request AND be queryable by the provider for this tier to work.
PARTIAL: provider returns an artifact ID only. Can confirm delivery after the fact, but cannot query outcome.
BLIND: none of the above. Cannot reconcile programmatically. Surfaces as a hard integration requirement, not something to paper over with retry logic.

A BLIND provider on timeout is a human review case. We surface this explicitly rather than letting it silently retry and double-execute.

What changed in practice

Switching from retry-on-timeout to reconciliation-on-timeout meant:

Zero duplicate bookings from network blips
A clear paper trail for every unresolved action
Provider integrations graded by what’s actually possible, not what we wished was possible

The tradeoff: more infrastructure, more state to manage, more explicit handling of ambiguity. Worth it. The alternative — pretending timeout means failure and retrying — was a silent correctness bug waiting to surface at the worst moment.

If your agent dispatches actions with real-world side effects, timeout is not a retry signal. It’s a reconciliation signal. Build for it.

Why “Would You Use This?” Is the Most Useless Question in Product Research

StareBrain — Fri, 16 Oct 2026 04:30:27 +0000

You’ve done it. I’ve done it. Everyone building something has done it.

You post your idea, your landing page, your demo. You ask “would you use this?” or “does this solve a problem for you?”

Everyone says yes.

You feel validated.

You learn nothing.

The Problem With Hypothetical Questions

“Would you use this?” is a hypothetical. It costs the person nothing to say yes. They’re imagining a future version of themselves in a future situation where they might need this thing.

That person isn’t real. Their answer isn’t real.

What you need is behavior, not intention. And behavior only exists in the past.

The Question That Actually Works

“Walk me through the last time you dealt with [the problem].”

Now they have to recall a real event. They can’t answer with a hypothetical. The story that comes out tells you more than a hundred survey responses.

Here’s what you learn that the first question never gives you:

1. What they actually did — not what they think they’d do

People who say they’d pay for a productivity tool already have a workaround. A spreadsheet, a Slack thread, a habit they built. They’re not planning to give it up. You only find that out by asking what they actually did last time.

2. What you’re really competing with

It’s almost never another product.

It’s “I just do it manually.” It’s “I ask my assistant.” It’s “I gave up and it never got done.”

Knowing the real alternative tells you what your bar actually is. You’re not competing with another SaaS — you’re competing with the path of least resistance.

3. Whether the problem is painful enough

If they struggle to recall the last time it happened — it’s not a burning problem. They won’t switch for it.

If they light up, lean forward, and tell you three stories — you have something.

The Follow-Up That Becomes Your Roadmap

After they tell you the story, ask: “What did you do next?”

Keep asking it. They’ll describe a chain of workarounds — the thing they tried first, the thing they fell back on, the step where they gave up.

That chain is your product roadmap. Each workaround is a step you could remove.

"Walk me through the last time you had to reschedule a meeting across three people."

→ "I went to my calendar..."
→ "What did you do next?"
→ "I checked their availability manually..."
→ "What did you do next?"
→ "I sent three separate messages..."
→ "What did you do next?"
→ "I waited two days and one person never replied so I just picked a time."

Every “what did you do next” reveals a friction point. You didn’t have to guess at them.

The Trap Most Builders Fall Into

**
The “would you use this?” question feels like validation because people say yes. It’s actually a trap — it filters for politeness, not pain.

The “last time” question feels riskier because it might reveal that the problem isn’t bad enough to solve. But that’s information. Better to learn it in a conversation than after six months of building.

A Framework for Better Research Questions

Instead of --> Ask
Would you use a tool for X? --> Walk me through the last time you did X
Is X a problem for you? --> How often does X come up? What did you do last time?
Would you pay for this? --> What have you already tried? What did it cost you?
Does this solve your problem? --> What did you do instead? Why didn’t that work?

The Real Signal

A return visit to your product after a week tells you more than any survey answer. But you don’t always have a product yet.

The “last time” question is how you get real signal before you build anything. It points at something that already happened — something that can’t be spun or optimized for politeness.

One conversation like this is worth more than a hundred “would you use this?” responses.

Go find one person. Ask them about the last time. See what you learn.

The Provider Capability Checklist Every Agent Builder Needs Before Writing a Single Line of Integration Code

StareBrain — Thu, 15 Oct 2026 03:56:26 +0000

Most agent integration bugs aren’t logic errors. They’re assumption errors — specifically, assumptions about what your provider will give you when something goes wrong.

Write the retry logic first, discover the provider gaps in production, add workarounds per-provider as bugs surface. That’s the default path. The workarounds are usually correct but undocumented, so the next provider gets the same treatment.

Three questions asked before integration starts costs ten minutes. The alternative costs more.

The Three Questions

Before wiring any provider into an agent’s action path:

Does a dispatch return a stable, queryable artifact ID?

This is the reconciliation anchor. If a dispatch times out before returning, you need something to look up later. If the provider returns nothing — or returns an ID that isn’t queryable — you have no anchor on timeout.

Does the provider accept an idempotency key or a reference ID you control?

This is what makes retries safe inside the consistency window. If the provider accepts a key you generate before dispatch, a retry with the same key returns the original result instead of creating a duplicate. Without it, a retry inside the window is a gamble.

Is there a queryable endpoint that returns current state by that ID?

This is what makes reconciliation possible after the fact. If you can query by the artifact ID and get current state, you can confirm delivery without re-dispatching. Without it, you’re reconciling blind.

*The Four Integration Tiers
*

`enum class ProviderCapabilityTier {
    FULL,           // Returns artifact ID + accepts idempotency key + queryable by ID
    RECONCILABLE,   // Returns artifact ID + queryable, no idempotency key support  
    PARTIAL,        // Returns artifact ID, no query endpoint
    BLIND           // None of the above
}

data class ProviderCapabilities(
    val returnsArtifactId: Boolean,
    val supportsIdempotencyKey: Boolean,
    val hasQueryEndpoint: Boolean
) {
    fun tier(): ProviderCapabilityTier = when {
        returnsArtifactId && supportsIdempotencyKey && hasQueryEndpoint -> 
            ProviderCapabilityTier.FULL
        returnsArtifactId && hasQueryEndpoint -> 
            ProviderCapabilityTier.RECONCILABLE
        returnsArtifactId -> 
            ProviderCapabilityTier.PARTIAL
        else -> 
            ProviderCapabilityTier.BLIND
    }
}`

What Each Tier Means for Your Integration

FULL — Safe by default

`class FullCapabilityDispatcher(val provider: FullProvider) {
    suspend fun dispatch(action: Action): ActionRecord {
        val idempotencyKey = generateIdempotencyKey(action)

        // Store before dispatch — key exists even if call times out
        val record = ActionRecord(
            actionId = action.id,
            dispatchId = idempotencyKey,
            delivery = DeliveryState.PENDING,
            eligibleForReconciliationAt = Instant.now().plus(provider.consistencyWindow)
        )
        store(record)

        val result = provider.dispatch(action, idempotencyKey = idempotencyKey)

        return record.copy(
            providerObjectId = result.artifactId,
            delivery = DeliveryState.PENDING // Still pending until lookup confirms
        )
    }
}`

A retry with the same idempotency key returns the original result. “Not found” inside the consistency window costs a wait, never a duplicate.

RECONCILABLE — Safe after the window

`class ReconcilableDispatcher(val provider: ReconcilableProvider) {
    suspend fun dispatch(action: Action): ActionRecord {
        val dispatchId = generateDispatchId(action)

        val record = ActionRecord(
            actionId = action.id,
            dispatchId = dispatchId,
            delivery = DeliveryState.PENDING,
            eligibleForReconciliationAt = Instant.now().plus(provider.consistencyWindow)
        )
        store(record)

        return try {
            val result = provider.dispatch(action)
            record.copy(providerObjectId = result.artifactId)
        } catch (e: TimeoutException) {
            // dispatchId is the reconciliation anchor
            // Can query by it after the consistency window closes
            record // Stays PENDING
        }
    }

    suspend fun reconcile(record: ActionRecord): ActionRecord {
        if (!record.isEligibleForReconciliation()) return record

        // Query by the dispatch ID we generated
        val artifact = provider.lookupByDispatchId(record.dispatchId)

        return if (artifact != null) {
            record.copy(
                providerObjectId = artifact.id,
                delivery = DeliveryState.CONFIRMED
            )
        } else {
            record.copy(delivery = DeliveryState.FAILED)
        }
    }
}`

No idempotency key support means retries inside the window are risky. The min-age gate matters more here — don’t retry until outside the consistency window.

PARTIAL — Proceed with documented risk

`class PartialCapabilityDispatcher(val provider: PartialProvider) {
    suspend fun dispatch(action: Action): ActionRecord {
        val record = ActionRecord(
            actionId = action.id,
            dispatchId = generateDispatchId(action),
            delivery = DeliveryState.PENDING,
            // Note: longer window because we can't query to confirm
            eligibleForReconciliationAt = Instant.now().plus(CONSERVATIVE_WINDOW)
        )
        store(record)

        return try {
            val result = provider.dispatch(action)
            // Has artifact ID but no query endpoint
            // Can only confirm by checking artifact indirectly
            record.copy(
                providerObjectId = result.artifactId,
                delivery = DeliveryState.PENDING
            )
        } catch (e: TimeoutException) {
            // No artifact ID returned, no query endpoint
            // Cannot reconcile programmatically
            record.copy(delivery = DeliveryState.DENIED_UNRESOLVED)
        }
    }
}`

Timeout with no artifact ID returned = DENIED_UNRESOLVED. Document this as a constraint on the integration, not a bug to fix later.

BLIND — Human review on timeout

`class BlindProviderDispatcher(val provider: BlindProvider) {
    suspend fun dispatch(action: Action): ActionRecord {
        // Document the constraint before the first line of integration code
        require(action.requiresHumanReviewOnTimeout) {
            "BlindProvider integrations must have human review configured for timeout cases"
        }

        val record = ActionRecord(
            actionId = action.id,
            dispatchId = generateDispatchId(action),
            delivery = DeliveryState.PENDING,
            humanReviewRequired = true
        )
        store(record)

        return try {
            provider.dispatch(action)
            // Even on success, no artifact ID to anchor reconciliation
            record.copy(delivery = DeliveryState.PENDING)
        } catch (e: TimeoutException) {
            record.copy(
                delivery = DeliveryState.DENIED_UNRESOLVED,
                humanReviewFlag = HumanReviewFlag(
                    reason = "Blind provider timeout — action may have succeeded",
                    requiredAction = "Manual verification required before retry"
                )
            )
        }
    }
}`

BLIND providers aren’t necessarily wrong to integrate — but the timeout path is manual by definition. Surface that to a human; don’t let DENIED_UNRESOLVED sit in a queue that auto-retries.

The Checklist in Practice

`fun evaluateProvider(provider: Provider): ProviderEvaluation {
    return ProviderEvaluation(
        provider = provider,
        capabilities = ProviderCapabilities(
            returnsArtifactId = provider.dispatchReturnSchema.contains("id"),
            supportsIdempotencyKey = provider.requestSchema.contains("idempotency_key") 
                || provider.requestSchema.contains("reference_id"),
            hasQueryEndpoint = provider.endpoints.any { it.queryableById }
        ),
        documentedConstraints = buildConstraintList(provider),
        recommendedTimeoutHandling = tier.timeoutStrategy()
    )
}`

Run this before writing integration code. The output is documentation that lives next to the integration, not assumptions that live in someone’s head.

What This Looks Like for StareBrain

For on-device agent actions on Android, the accessibility layer confirms the UI action happened — the tap fired, the button was pressed. Whether the downstream provider recorded the result is a different question answered by a different clock.

A calendar booking confirmed by the accessibility service is one verification. The calendar provider returning a queryable event ID is a second, independent verification. They answer different questions. The provider capability tier determines which of those two verifications you can actually perform.

Ten minutes upfront. Document the tier. Design the timeout path before you need it.

The Lookup That Lies: Why Your Agent’s Retry Logic Has a Hidden Race Condition

StareBrain — Wed, 14 Oct 2026 04:00:13 +0000

Your agent dispatches an action. You run a provider lookup immediately after to confirm it happened. The lookup returns “not found.” You mark it failed. You retry.

Except the action succeeded. Your lookup just ran inside the provider’s replication window.

You just caused a duplicate.

This isn’t a bug in your retry logic. It’s a bug in your trust model for the lookup itself.

The Problem: Write Success ≠ Read Availability

Some providers are eventually consistent. The write succeeds — HTTP 200, no error. But the artifact isn’t immediately queryable on the read replica. Depending on the provider and load, the replication lag might be 200ms, 2 seconds, or 30 seconds.

A lookup that runs immediately after dispatch is reading from a clock that hasn’t caught up.

Two failure modes that look identical:

Lookup result: "not found"
Case A: Action genuinely failed — nothing was written
Case B: Action succeeded — read replica hasn't caught up yet

Both return the same thing. Only Case A should trigger a retry.

The Naive State Machine Gets This Wrong

`suspend fun confirmDispatch(record: ActionRecord, provider: ActionProvider): ActionRecord {
    val artifact = provider.lookup(record.dispatchId)

    return if (artifact != null) {
        record.copy(delivery = DeliveryState.CONFIRMED)
    } else {
        // BUG: This assumes "not found" means "failed"
        // It might just mean "not propagated yet"
        record.copy(delivery = DeliveryState.FAILED)
    }
}`

If this runs immediately after dispatch, a “not found” response is ambiguous. You cannot distinguish a genuine failure from a replication lag.

The Fix: A Minimum Age Gate

Don’t allow a PENDING record to enter reconciliation until the consistency window has closed:

`data class ActionRecord(
    val actionId: String,
    val dispatchId: String,
    val providerObjectId: String?,
    val delivery: DeliveryState,
    val acceptance: AcceptanceState,
    val dispatchedAt: Instant,
    val confirmedAt: Instant?,
    val eligibleForReconciliationAt: Instant  // dispatched_at + consistency_window
)

fun ActionRecord.isEligibleForReconciliation(): Boolean {
    return Instant.now().isAfter(eligibleForReconciliationAt)
}`

The reconciliation loop checks eligibility before running a lookup:

`suspend fun reconcileIfEligible(
    record: ActionRecord,
    provider: ActionProvider
): ActionRecord {
    if (!record.isEligibleForReconciliation()) {
        // Too early — lookup result cannot be trusted
        return record
    }

    val artifact = provider.lookup(record.dispatchId)

    return if (artifact != null) {
        record.copy(
            providerObjectId = artifact.id,
            delivery = DeliveryState.CONFIRMED,
            confirmedAt = Instant.now()
        )
    } else {
        // Now "not found" actually means failed
        // The consistency window has closed
        record.copy(delivery = DeliveryState.FAILED)
    }
}`

Where N Comes From

The consistency window duration isn’t arbitrary:

`object ConsistencyWindows {
    // From provider documentation
    val STRIPE_EVENTS = Duration.ofSeconds(5)

    // From empirical observation (no SLA published)
    val GOOGLE_CALENDAR = Duration.ofSeconds(10)

    // Conservative default when nothing is documented
    val DEFAULT = Duration.ofSeconds(30)
}

fun ActionRecord.withConsistencyWindow(provider: ProviderType): ActionRecord {
    val window = when (provider) {
        ProviderType.STRIPE -> ConsistencyWindows.STRIPE_EVENTS
        ProviderType.GOOGLE_CALENDAR -> ConsistencyWindows.GOOGLE_CALENDAR
        else -> ConsistencyWindows.DEFAULT
    }
    return copy(
        eligibleForReconciliationAt = dispatchedAt.plus(window)
    )
}`

If the provider doesn’t publish their replication lag, measure it. Dispatch a test write, poll the read endpoint, record when it becomes visible. Do this under load, not just in ideal conditions.

The Late Confirmation Race

There’s a related problem: what happens when a confirmation arrives after you’ve already marked a record FAILED and queued a replacement?

`suspend fun handleLateConfirmation(
    record: ActionRecord,
    artifact: ProviderArtifact
): ActionRecord {
    return when (record.delivery) {
        DeliveryState.FAILED -> {
            // Late confirmation — action succeeded despite our earlier verdict
            // Cancel any queued replacement before updating state
            cancelQueuedReplacement(record.actionId)

            record.copy(
                providerObjectId = artifact.id,
                delivery = DeliveryState.CONFIRMED,
                confirmedAt = Instant.now()
            )
        }
        DeliveryState.PENDING -> {
            // Normal confirmation path
            record.copy(
                providerObjectId = artifact.id,
                delivery = DeliveryState.CONFIRMED,
                confirmedAt = Instant.now()
            )
        }
        DeliveryState.CONFIRMED -> {
            // Already confirmed — idempotent, no change
            record
        }
    }
}`

The replacement dispatch must read delivery state immediately before firing — not at the time it was scheduled. Scheduling a replacement and dispatching one are two separate moments. The state check belongs at dispatch.

What This Looks Like in the Full State Machine

`enum class DeliveryState {
    PENDING,      // Dispatched, awaiting confirmation
    CONFIRMED,    // Provider lookup returned the artifact
    FAILED        // Lookup returned nothing AFTER consistency window closed
}

// DENIED_UNRESOLVED requires a lookup outside the consistency window
// before it can transition to FAILED
fun ActionRecord.resolvedStatus(): ActionStatus = when {
    delivery == DeliveryState.PENDING && 
        !isEligibleForReconciliation() -> ActionStatus.DENIED_UNRESOLVED  // Window still open
    delivery == DeliveryState.PENDING && 
        isEligibleForReconciliation() -> ActionStatus.DENIED_UNRESOLVED   // Needs lookup
    delivery == DeliveryState.FAILED -> ActionStatus.FAILED
    delivery == DeliveryState.CONFIRMED && 
        acceptance == AcceptanceState.REJECTED -> ActionStatus.FAILED
    delivery == DeliveryState.CONFIRMED && 
        acceptance == AcceptanceState.ACCEPTED -> ActionStatus.CONFIRMED
    else -> ActionStatus.DENIED_UNRESOLVED
}
`

DENIED_UNRESOLVED doesn’t decay into FAILED on a single early lookup. It requires a lookup that runs outside the consistency window. A lookup inside the window is evidence of nothing.

The Practical Implication

The consistency window is part of your verification model. If it isn’t documented somewhere in your code — as a named constant, not a magic number — it’s an assumption. And assumptions are where duplicate dispatches live.

For StareBrain’s on-device actions, this matters particularly for anything that touches an external provider after the accessibility layer fires. The accessibility service can confirm the UI action happened. Whether the downstream provider has recorded it is a different clock entirely.

Two clocks. One verification model. The gap between them is where your duplicates come from.