Vendor monitor agent

This page explains how a vendor monitor agent uses Track to keep a long-lived watch on vendor pricing pages, SLA and terms pages, and status pages: the first run builds a baseline, later runs compare against it on a schedule, and hits notify the owner with a diff and sources. After reading it, you will understand why this scenario's backbone is a long-lived monitor rather than memory, where baselines and per-run diffs should live, and why watching public pages only needs a silently issued runtime credential.

Use case

Procurement, legal, or security teams need to monitor vendor pricing, terms of service, security announcements, and product changes. Vendors rarely announce these updates: pricing pages shift quietly, SLA terms change during a redesign, and status pages record incidents that never reach email. Manual patrols consume time and cannot prove "what the terms looked like at the last check."

Typical triggers:

• Before a contract renewal, the team must confirm how the vendor's SLA and terms changed since signing.
• An incident appears on a vendor status page, and its impact on the business must be assessed.
• An annual procurement review needs a change timeline of each vendor's pricing page as negotiation input.

Engineering challenges

• Signal-to-noise in change detection: vendor pages get redesigned often, and visual or structural churn far outnumbers substantive change. Misreporting "the page was redesigned" as "the terms changed" trains owners to ignore alerts within a few rounds.
• Baseline management: deciding "did it change" requires knowing "what it looked like last time." Baselines must be versioned, replayable, and rebuildable after a redesign with human confirmation — snapshots scattered on a script's local disk cannot support evidence at renewal negotiations.
• Alert credibility: an alert like "SLA dropped from 99.9% to 99.5%" must point back to the exact page, the section-level diff, and the capture time; a change verdict without a source has no actionable value.

Module composition

Module	Role	Notes
GenAuth	Core	Silent delegation issues the short-lived runtime credential every product call requires; interactive consent is only needed when login state or write actions enter the picture — see "When interactive consent is needed" below.
Web Agent	Core	Track maintains the long-lived monitor: the first run builds a baseline, scheduled runs re-fetch and compare, and hits notify via callback; a one-off check can fall back to a single-round patrol.
GUMem	Not used	Page baselines and per-run diffs are business state, not user memory — they live in Track's run snapshots and your baseline store, managed by version. Memory plays no part in this scenario.

When interactive consent is needed

Every product call requires a GenAuth delegate token; public read-only scenarios are covered by silent delegation. This scenario watches public pages by default (pricing pages, public terms pages, status pages) and needs no interactive confirmation in the Console:

• Public reads: issue a runtime credential silently with delegateToken. The credential is short-lived and revocable at any time; after revocation the monitor's next fetch fails immediately, and every issuance and fetch enters the audit chain.
• Signed-in targets or write actions: only when the monitoring target is a vendor's signed-in backend (for example, contract pricing or billing pages), or any write action on a site is involved, switch to mode: 'interactive' so the owner approves in Qoni Console. The example on this page includes no such target.

Note: the SDK example requests product-level authorization. Fine-grained boundaries — vendor domain lists and page ranges — are enforced by the GenAuth Agent Profile or your policy layer, not by the monitoring intent text; that configuration is not shown on this page. See Delegate token and attenuation for the full semantics.

Workflow

1. The team picks the vendor pages to watch, the sections that matter, and the check frequency.

2. Your app silently issues a runtime credential and loads the current version of the monitor policy from your policy store.

3. Your app creates the Track monitor; the first run fetches the target pages and builds the baseline (baseline_extracted).

4. Every scheduled run afterwards fetches the current pages and compares against the baseline; whether something changed is decided by rules, not by model wording.

   Checkpoint: When a full-page redesign breaks the comparison, treat it as a failure — replay that run and rebuild the baseline after human confirmation, instead of misreporting the redesign as a terms change.

5. On a hit, Track calls back to your app with the section-level diff, source URLs, and snapshots.

6. Your app validates the change entries (no source, no alert), writes the new baseline and diff to the baseline store, and notifies the owner.

   Checkpoint: Every alert should trace back to a concrete section diff and source page; risk grading and follow-up stay with the owner — the Agent never issues high-risk verdicts on its own.

Example code

The example below sets up the long-lived monitor with the official Qoni SDK (@qoniai/qoni): silently issue a runtime credential → load the versioned monitor policy from your policy store → create the Track monitor → pause and resume scheduling when needed.

Draft interface

Draft interface — the unified SDK's Track signatures are not final; the example expresses integration intent. See Track.

import { Qoni } from '@qoniai/qoni'

const qoni = new Qoni({
  accessKey: process.env.QONI_ACCESS_KEY!,
  secretKey: process.env.QONI_SECRET_KEY!,
})

export async function createVendorMonitor(vendorPages: string[]) {
  // 1. Silent delegation: public-page watching, no site sign-in involved;
  //    the credential is revocable at any time
  const { data: grant } = await qoni.delegateToken({
    user: { id: process.env.QONI_USER_ID! },
    agent: 'vendor-monitor',
    products: ['track'], // final shape of Track product authorization follows the released signature
  })

  // 2. Before creation: load the current monitor policy from YOUR policy store (not Memory)
  const policy = await loadMonitorPolicy() // e.g. { version: '2026-08', watchedSections: [...], thresholds: ... }

  // 3. Create the long-lived monitor: the first run builds the baseline,
  //    later runs compare on the schedule
  const { data: monitor } = await qoni.track.create({
    token: grant.token,
    intent: `
      Watch these vendor pages for pricing, SLA/terms and status changes:
      ${vendorPages.join(', ')}.
      A visual redesign alone is not a change — report only when the
      monitored sections below actually change, with a section-level diff
      and the source URL for every change.

      Monitor policy (version ${policy.version}):
      ${JSON.stringify(policy)}
    `,
    schedule: { kind: 'interval', intervalSeconds: 3600 },
    notify: { kind: 'callback_url', url: 'https://app.example.com/hooks/vendor-track' },
  })

  // Store the monitor reference with the policy version for callback handling and replay
  await saveMonitorRef(monitor.id, { policyVersion: policy.version })
  return monitor
}

// Pause scheduling during a negotiation window or vendor maintenance, resume afterwards
export async function pauseVendorMonitor(monitorId: string, token: string) {
  await qoni.track.pause(monitorId, { token })
}

export async function resumeVendorMonitor(monitorId: string, token: string) {
  await qoni.track.resume(monitorId, { token })
}

On a hit, Track calls your notify.url. Callback handling belongs to your app: parse the change entries, drop anything without a diff or source URL, write the new baseline and diff to the baseline store together with the policy version, and only then notify the owner — this validation layer is what keeps alerts credible.

Single-round fallback: if you do not need a long-lived monitor yet (for example, a one-off check before renewal), use the documented doAnything.run() for a single read-only patrol — silently delegate the webagent.do_anything product, fetch the target pages in one call, and produce a diff against your stored baseline, with comparison and alerting logic on the app side as well. In both shapes, baselines go to the baseline store, never to Memory.

Data and memory boundaries

This scenario touches four kinds of data; none of them belongs in GUMem:

• Versioned rules: monitored-section lists, trigger thresholds, alert escalation rules — managed by version in your policy store, with every alert referencing the policy version.
• Business state: page baselines, per-run diffs, snapshots — carried by Track's run records and your baseline store, versioned and replayable.
• Audit records: the behavior chain of credential issuance and every fetch — maintained by GenAuth.
• User Memory: this scenario does not use GUMem. Baselines and diffs are business state, not user preferences; writing them into Memory only creates a second, unreconcilable source of truth.

Failure handling

Situation	Recommended handling
A full-page redesign breaks the comparison	Treat it as a failure and replay that run; rebuild the baseline after human confirmation, never misreport the redesign as a terms change.
The monitor keeps failing (consecutive_failures grows)	The monitor enters an abnormal state; check target reachability and rule configuration, then verify once with run_now after the fix.
A target page shows a login wall or CAPTCHA	Track signals that a human is needed; the owner responds (intervene) — no silent bypass.
A callback entry lacks a diff or source	App-side validation drops the entry and records how many were dropped; no source, no alert.

Production notes

A page change is not yet a real risk: Track decides "it changed," while risk grading and follow-up always stay with the owner. Monitoring is read-only and notify-only — it never executes contract or procurement actions on a human's behalf. Set a floor on the schedule interval based on how often the pages actually update, to avoid load on vendor sites; monitors are long-lived, so transfer ownership and re-review notify channels when team members change.

Next steps

• Read Track for the monitor's full lifecycle and event stream.
• Read the Quickstart to run the shortest path for Agent identity and delegation.
• Continue with the Partner portal monitoring agent for an adjacent signed-in monitoring scenario.