Intents and resolution

The engine uses “intent” for two related contracts: an action proposed by a frame policy and a request being checked at the execution boundary. They have different payloads and different resolution rules.

Policy action intents

Return an action intent inside an onFrame result. For example, an exit policy returns:

const result = {
  policyId: "example-exit",
  status: "triggered",
  reason: "Configured exit condition reached",
  intent: {
    kind: "close_position",
    position: currentPosition,
    priority: 20,
    confidence: 1,
    reason: "Configured exit condition reached",
  },
};

This is a shape example: currentPosition must be a real position read from the session. The complete exit example shows that lookup.

side is optional descriptive direction (LONG or SHORT); it does not construct an order. Place intents need an actual order with its action, quantity, instrument, and other required fields.

How one frame action wins

The resolver reads context.getPositions() and uses the first position's action to determine whether a position exists. It excludes none, excludes place intents while a position exists, and excludes close intents while flat.

Eligible intents are sorted by:

1. Kind rank, highest first.
2. intent.priority, highest first, defaulting to zero.
3. intent.confidence, falling back to the frame result's confidence, highest first.

An entry with priority 1000 does not outrank a close with priority 1. Kind rank comes first. Equal comparisons retain input order. Avoid relying on ties to express an important trading rule.

The resolver returns one winner or null. It does not validate every payload, select positions across a portfolio, or try the next candidate after execution fails. A winning close without position is rejected by the executor rather than replaced by the runner-up.

What block actually does

A block wins over lower-ranked candidates in the same policy batch. Its executor returns true without submitting an action or calling skipall(). It does not install a persistent directive or stop other scripts from requesting execution.

Likewise, status: "blocked" without an intent does not block a competing policy action. Use the frame intent to influence frame resolution and an intent check to gate other execution requests.

Execution intents

The L3 module's exported intent(args) receives args.intent. For an order request, the payload is under options.order, not directly under order:

const requestShape = {
  kind: "place_order",
  source: "sjs",
  options: {
    order: { action: "BUY", quantity: 1 },
    opt: { metadata: { motive: "strategy_entry" } },
  },
};

This abbreviated illustration omits runtime context and complete order fields. The engine builds the execution request when a strategy calls its session API.

The execution-intent type also includes cancel_all_orders, close_all_positions, set_automation_mode, and set_runtime_flag. These are not additional action kinds handled by the policy frame executor. Do not infer support for returning them as a PolicyIntent.

Combining execution checks

runPolicyIntentChecks visits every policy sequentially and collects returned results. resolveIntentChecks allows the request only if no check returns allowed: false. It does not rank checks by priority or confidence, and it permits an empty list.

The quickstart wires this aggregate Boolean into the L3 intent export. Returning a check object directly from that export is incorrect: the runtime expects the final Boolean.

Execution source and metadata

The frame executor submits actions with source l3, so those actions bypass the L3 intent hook while remaining subject to automation controls. Validate frame-produced actions in the policy that creates them.

The executor preserves custom intent metadata and adds a policyStack record with the policy ID, reason, confidence, reservation key, and position episode key. Reservation and episode keys are metadata here; supplying them does not implement a reservation store or general duplicate suppression.

For accepted place/modify/cancel/close requests the executor invokes the frame's skipall() and returns true. “Accepted” means the API result was neither false, undefined, nor null; it does not mean a broker fill occurred.

Continue with Execution flow, State and lifecycle, or Examples.