OK

OK stands for Operational Knowledge. Nova uses operational knowledge for current service state: which service a tab belongs to, which visible facts are fresh enough, and which assumptions need a new observation before they can guide action.

OK is Nova’s live knowledge layer for running web services in browser tabs. It stores observations about the visible service state, then turns accepted observations into current facts with confidence, freshness, and conflict handling.

OK is different from PKS and ETM. PKS stores reusable website behavior. ETM stores task-shaped episodes and completion conditions. OK answers the immediate question: what appears true right now in this tab or service context?

Agents do not use OK as a manual notes store. Normal browser tool calls can refresh target and service state automatically. An agent uses OK observation only when an important visible state would otherwise be missed, such as login state, selected model, plan tier, page type, language, theme, or available service features.

In short

• OK stores current service state, not long-term website playbooks.
• A single observation call can report several structured claims from the same page snapshot.
• Accepted claims become current facts; weak or contradictory claims may stay as observations or produce warnings.
• Freshness matters: facts older than the OK hint window are refreshed before they guide state-sensitive work.
• Unknown canonical core signals are rejected, while custom namespaced signals can extend the observation surface.
• OK can support rule checks and task context, but it does not override current-page confirmation or user approvals.

What OK stores

OK keeps a compact state picture around the current browser target, detected service, and visible service facts.

1. Target and service context OK can associate a browser target with a recognized web service, current URL, origin, route, and binding state.
2. Observations An observation records what an agent or system signal noticed at a specific moment. Agent observations are submitted as structured claims.
3. Facts A fact is the current accepted value for a signal in a target or service binding, such as login state, selected model, plan tier, page type, language, or theme.
4. Freshness OK compares observation time with the current page context. Perception can return hints when facts are missing, older than the freshness window, or tied to a changed URL.
5. Conflict handling When a new value contradicts the current fact, OK either keeps the existing fact, marks conflict, or supersedes it with stronger evidence.
6. Derived capabilities Some service facts can become capabilities, for example whether a service appears authenticated or whether a feature appears available.

When this matters

OK belongs to tasks that depend on live website state: checking whether a user appears signed in, which model or plan is visible, whether a feature is available, whether a route changed after navigation, or whether the current state is too uncertain for a reliable next step.

Operational model for agents

For an agent, OK answers four questions: which service context is active, which visible claims can be reported, which facts are current enough, and which uncertainty must be resolved before acting?

Target and binding

The browser target and detected service context where an observation belongs. A fact from one target should not be silently reused for another target.

Signal key

A structured key that names a state signal. Canonical public keys use the core namespace; custom service-specific keys must still follow a namespace.path format.

Claim

One reported observation inside an OK call. A claim contains the signal key, the observed value, optional evidence, and certainty.

Fact

The current accepted value for a signal after OK has processed observations, confidence, supersedence, and conflicts.

Certainty

The agent’s confidence level for a claim. Certain claims are strong, likely is the default, and tentative claims are weak orientation.

Freshness

The age and page fit of a fact. Perception asks for a new observation when relevant facts are missing, old, or tied to a previous URL.

Capability

A usable state derived from facts, such as an authenticated service or visible feature availability.

How agents use OK information

For agents, OK is a live state surface. It tells the agent when to observe, how to report visible state, and when stored state is too old, weak, or conflicted to guide a state-sensitive action.

1. Read the current page The agent uses nova.perceive or another read tool to inspect the visible page. Perception can include okHints when operational state needs attention.
2. Check OK hints If okHints.shouldObserve is true, the agent reads missingOrStaleKeys, firstVisit, and urlChanged before deciding what to report.
3. Report only visible state The agent calls nova.ok_observe with claims that are visible on the current page. It should not report passwords, tokens, hidden account data, or guesses.
4. Let OK process the claims OK returns accepted, rejected, superseded, facts[], and optional warnings[] so the agent can see what happened.
5. Use state as orientation Fresh facts can guide later choices, but current page observation and safety boundaries still decide whether an action is allowed.
6. Refresh uncertain state If a fact is stale, tentative, conflicted, or tied to an old URL, the agent should re-observe before relying on it for login, account, model, billing, or feature-sensitive behavior.

When OK state applies

OK state is not permission to click. It is reliable orientation only when the current page still supports the fact and the fact state is strong enough for the next step.

Failure and guard conditions

These are the hard edges an agent or integration should expect from the OK observation contract.

Agent interpretation example

The example shows OK as a current-state contract: perception asks for fresh state, the agent reports visible claims, and the result tells the agent which facts can be used as orientation.

Observation request

{
  "tool": "nova.ok_observe",
  "arguments": {
    "targetId": "active",
    "perceptionId": "perceive_7f3a",
    "claims": [
      {
        "signalKey": "core.login_state",
        "value": "logged_in",
        "certainty": "likely",
        "evidence": "Visible user menu is present."
      },
      {
        "signalKey": "core.plan.tier",
        "value": "pro",
        "certainty": "tentative",
        "evidence": "A Pro label is visible near the account menu."
      }
    ]
  }
}

Relevant response fields

{
  "structuredContent": {
    "ok": true,
    "accepted": 2,
    "rejected": 0,
    "superseded": 0,
    "facts": [
      {
        "key": "core.login_state",
        "value": "logged_in",
        "state": "fresh",
        "isNew": true
      }
    ],
    "warnings": null
  }
}

Agent interpretation

{
  "treatAs": "current service-state evidence",
  "mayUse": "fresh facts can guide model, login, page-type, or feature-sensitive choices",
  "beforeAction": "confirm the visible page still supports the fact",
  "onStaleOrConflict": "perceive again and submit a fresh OK observation"
}

MCP contract

This is the deterministic layer below the explanation. It lists OK fields that agents and integrators should treat as contract signals rather than free prose.

Execution rule: No OK fact may guide state-sensitive action without current-page confirmation.