Section 08

Debugging With Agent Markers

Set up the agent-markers files and configuration for this browser project, then verify the setup before investigating any specific bug.


setup agent prompt
Set up the agent-markers files and configuration for this browser project, then verify the setup before investigating any specific bug.

1. Inspect the existing agent-markers package and demo files first:
   - packages/client/src/index.ts
   - packages/client/src/collector.ts
   - packages/client/src/types.ts
   - packages/client/src/capture/console.ts
   - packages/client/src/capture/fetch.ts
   - packages/client/src/capture/errors.ts
   - packages/client/src/serialize.ts
   - apps/demo/src/main.ts
   - apps/demo/src/viewer.ts
   - scripts/smoke-demo.mjs
   - docs/WORKSHOP.md

2. If the package or demo is missing, scaffold the smallest matching structure. If files already exist, preserve the current API where possible and extend it only as needed.

3. Define or confirm the core schema:
   - DebugSession: one bounded run with sessionId, appName, schemaVersion, CapturedEvent[], and DebugMoment[]
   - CapturedEvent: id, sequence, timestamp, type, and metadata for console, fetch, error, manual, DOM, screenshot, or app events
   - DebugMoment: id, label, note, optional nextAction, timestamp, and nearbyEventIds that reference CapturedEvent ids
   - export JSON: a JSON-serializable packet that can be saved, attached to a test run, or passed to another agent

4. Implement or confirm createAgentMarkers in packages/client/src/index.ts. It should accept appName, exposeGlobal, and capture options for console, fetch, and errors. It should return mark(...), export(), and stop().

5. Implement console, fetch, error, and manual capture:
   - console capture records log/warn/error metadata without creating recursive logging loops
   - fetch capture records URL, method, status, timing, and failure metadata
   - error capture records thrown errors and unhandled rejections
   - manual capture records marker labels, notes, nextAction, and timing
   - all captured events should receive stable ids and sequence numbers

6. Add privacy-safe defaults:
   - capture metadata by default
   - do not export storage values, cookies, tokens, request bodies, response bodies, private DOM text, or screenshots unless deliberately enabled and reviewed
   - redact sensitive query params, headers, stack paths, and visible private text before saving export JSON
   - include redaction notes in the exported packet

7. Implement the collector in packages/client/src/collector.ts. Store events in order, enforce a maximum event count, and calculate nearbyEventIds for each DebugMoment using sequence or timestamp proximity.

8. Implement serialize.ts so export() always returns valid JSON without circular references. Optional DOM or screenshot fields should be marked unavailable when no hook is configured.

9. Wire createAgentMarkers into the demo app in apps/demo/src/main.ts with exposeGlobal: true for dev/test and capture enabled for console, fetch, and errors. Add a manual marker entrypoint such as a debug button or keyboard shortcut that calls markers.mark({ label, note, nextAction }).

10. Wire apps/demo/src/viewer.ts so the current session can be exported, displayed, copied, or downloaded as JSON.

11. Expose the dev/test global surface when configured:
   - window.__AGENT_MARKERS__.mark(...)
   - window.__AGENT_MARKERS__.export()
   - window.__AGENT_MARKERS__.stop()

12. Add test-runner export. In a Playwright-style test or equivalent, wait until the app is ready, call window.__AGENT_MARKERS__.mark(...), export the session with page.evaluate, and attach or save agent-markers.json. Assert markers.length > 0, a non-empty note exists, nearbyEventIds is present, and console/fetch/error/manual events appear when enabled.

13. Add bounded replay packet setup for one marker. The packet should include schemaVersion, sessionId, markerId, markerCutoffSeq, nearbyEventIds, filtered console/fetch/error/manual evidence, optional DOM/screenshot availability, included and excluded boundaries, maximum event count, redaction status, and the first verification command. Do not build a full recorder.

14. Update scripts/smoke-demo.mjs so it can launch or exercise the demo, create one marker, trigger at least one console event, fetch event, and error event where practical, export JSON, parse it, and confirm the packet is non-empty.

15. Verify with the available project commands:
   - npm test
   - npm run typecheck
   - npm run build
   - npm run smoke:demo

16. Confirm setup worked:
   - createAgentMarkers imports and initializes
   - mark() creates a DebugMoment with a specific note
   - nearbyEventIds is non-empty after nearby capture activity
   - exported events include console, fetch, error, and manual types when enabled
   - export JSON parses cleanly
   - window.__AGENT_MARKERS__ is available in dev/test only
   - stop() restores patched console, fetch, and error listeners
   - test-runner export saves or attaches agent-markers.json
   - privacy defaults exclude sensitive values

Report the files changed, setup choices, verification commands and results, sample export path, privacy boundaries, unavailable hooks, and any failed checks. If setup checks fail, stop and report the blocker. Do not debug a specific product bug until the setup and verification pass.

Workflow route

Debugging With Agent Markers

Set up the agent-markers files and configuration for this browser project, then verify the setup before investigating any specific bug.

Eggo pins the marked moment to nearby evidence for the Debugging With Agent Markers workflow, making the page's operating move visible.
Intent

Name the software-workflow decision before launching work.

Evidence

Inspect the file, command, log, prompt, or recording that proves the state.

Route

Pick the narrow agent, tool, shell, or council path that matches the problem.

Verify

Confirm the result with output, screenshots, receipts, or saved decisions.

  1. Big Idea
  2. Try This Now
  3. Start With 5 Monkeys
  4. Files To Inspect
  5. When To Reach For This
  6. How This Used To Work
console, fetch, error, and manual cards gather around one debug moment

Big Idea

Start by sending cheap perspective-based agents through weird paths. Then use agent markers to capture the exact moment that should become a bounded debug packet.

Core pattern:

snippet-1
5 Monkeys QA -> mark -> capture -> explain -> review/export

The 5 Monkeys pattern finds strange states a happy-path check would miss. Agent markers turn one of those strange states into evidence another agent can use.

An agent marker is a human-intent anchor inside a debugging workflow.

It answers:

Agent markers are not full replay systems. They are bounded debug packets.

Try This Now

Create one marker for a checkout UI bug: window.__AGENT_MARKERS__.mark({ label: "checkout disabled unexpectedly", note: "Expected submit to enable after terms and shipping were selected." }) Export the session and check that the marker has nearby evidence, not just a label.

Start With 5 Monkeys

Use 5 Monkeys before marker capture when the bug is vague, stateful, or hidden behind normal user behavior.

Assign one lens per pass:

LensWhat It Tries
expert power usershortcuts, fast navigation, hidden affordances
brand-new first-time userconfusion, missing affordances, unclear copy
inexperienced useraccidental clicks, mistaken paths, recovery failures
impatient returning userrapid clicks, skipped steps, partial flows

Make each pass explore weird paths:

Write each pass to a discardable QA note such as .notes/qa-01.md. Collate the findings, keep only useful bugs, and mark the one moment that best captures the state failure.

Then capture that moment with agent markers:

snippet-2
weird state found -> human marks the decisive moment -> export nearby evidence

Do not replace stable business-logic tests with 5 Monkeys. Use it to discover UI and state failures that tests and logs did not already isolate.

Files To Inspect

Agent markers project references:

snippet-3
packages/client/src/index.ts
packages/client/src/collector.ts
packages/client/src/types.ts
packages/client/src/capture/console.ts
packages/client/src/capture/fetch.ts
packages/client/src/capture/errors.ts
packages/client/src/serialize.ts
apps/demo/src/main.ts
apps/demo/src/viewer.ts
scripts/smoke-demo.mjs
docs/WORKSHOP.md

When To Reach For This

Use markers when logs are real but the important moment still needs human context.

Use Markers ForWhy
checkout bugmark the exact UI state where expected and actual diverge
auth/session refresh issuecapture nearby fetch/error/console evidence around the failure
billing admin UI failureattach human expectation to the visible broken state
flaky browser testexport a debug packet from the test runner
design/debug reviewpair screenshot/DOM hooks with a human explanation
long agent debugging sessionleave explicit breadcrumbs for the next pass

Skip markers when:

How This Used To Work

What you used to expect:

snippet-4
If enough logs are captured, the agent can infer the important moment.

What the workflow gives you now:

snippet-5
Logs show events. A marker ties a specific moment to human intent, nearby
evidence, and the next debugging question.

What you used to expect:

snippet-6
A screenshot or console dump is enough context.

What the workflow gives you now:

snippet-7
The useful packet combines the marker note, nearby console/fetch/error/manual
events, optional DOM or screenshot capture, privacy boundaries, and an export.

The Mental Model

snippet-8
DebugSession
-> CapturedEvent[]
-> DebugMoment[]
-> export JSON
-> agent prompt / test artifact / work unit
ConceptMeaning
DebugSessionone bounded debugging run
CapturedEventconsole, fetch, error, manual, DOM, screenshot, or app event
DebugMomentthe human marker: label, note, timestamp, nearby evidence
nearbyEventIdsevent ids around the marked moment
export JSONportable debug packet
stop()cleanup that restores patched browser APIs

Basic Browser Setup

Create markers in a browser app:

ts
import { createAgentMarkers } from "@agent-markers/client";

const markers = createAgentMarkers({
  appName: "checkout-app",
  exposeGlobal: true,
  capture: {
    console: true,
    fetch: true,
    errors: true,
  },
});

Expose a manual marker action:

ts
document.querySelector("#mark-debug")?.addEventListener("click", () => {
  markers.mark({
    label: "checkout payment method disappeared",
    note: "Expected saved payment selector to stay visible after refresh.",
  });
});

Export:

ts
const session = markers.export();
console.log(JSON.stringify(session, null, 2));

Clean up patched APIs:

ts
markers.stop();

Global Test Surface

In dev/test, expose the marker surface:

ts
createAgentMarkers({
  appName: "checkout-app",
  exposeGlobal: true,
});

Then inspect from the browser console or a test runner:

js
window.__AGENT_MARKERS__.mark({
  label: "checkout failure",
  note: "Expected saved cards to render before submit.",
});

const session = window.__AGENT_MARKERS__.export();
session.markers.length;

Use the global for test export, not as the only application API.

Capture Types

CaptureWhat It AddsWatch For
consolelogs, warnings, errorsnoisy output
fetchrequest URL, method, status, timingrequest/response bodies may be sensitive
errorsthrown errors and unhandled rejectionsstack traces may include private paths
manualhuman-entered labels and notesmust be specific
DOM hookoptional host-provided DOM snapshotavoid private text
screenshot hookoptional host-provided image captureunavailable in some environments
storage metadatakeys/counts, not full values by defaultnever dump secrets by accident

Privacy rule:

snippet-15
Capture metadata by default. Capture values only when deliberately enabled and safe.

Marker Shape

A useful marker has:

json
{
  "label": "checkout saved card missing",
  "note": "Expected saved payment methods to appear after login refresh; actual UI shows empty selector.",
  "nextAction": "Inspect auth refresh state, checkout payment query, and recent fetch events."
}

Weak marker:

json
{
  "label": "broken"
}

Better marker:

json
{
  "label": "saved payment selector empty after refresh",
  "note": "At this moment the user is logged in, the account menu shows the correct user, but checkout has no saved cards.",
  "nextAction": "Compare account payment fetch response with checkout payment state."
}

Export A Debug Packet

Export from browser:

js
const session = window.__AGENT_MARKERS__.export();
console.log(JSON.stringify(session, null, 2));

Save in a test:

ts
const session = await page.evaluate(() => window.__AGENT_MARKERS__.export());
await testInfo.attach("agent-markers.json", {
  body: JSON.stringify(session, null, 2),
  contentType: "application/json",
});

Or write to disk in a local script:

js
const session = await page.evaluate(() => window.__AGENT_MARKERS__.export());
await fs.promises.writeFile(
  "artifacts/agent-markers/checkout-session.json",
  JSON.stringify(session, null, 2)
);

Verify The Project

Common checks:

bash
npm test
npm run typecheck
npm run build
npm run smoke:demo

What to look for:

Turn A Marker Export Into An Agent Prompt

Prompt shape:

markdown
# Debug Prompt From Agent Marker

## Source Artifact

- marker export:
- schema version:
- marker id:
- marker label:

## Human Explanation

- expected:
- actual:
- why this moment matters:
- next action:

## Nearby Evidence

- console:
- fetch:
- error:
- manual:
- screenshot:
- DOM:

## Privacy Boundary

- storage values exported? no
- request bodies exported? no
- response bodies exported? no
- private text removed:

## Task

Find the smallest likely bug path and propose the first verification command.
Do not invent app state that is not in the marker packet.

Bounded Replay Capsule

Do not build a full recorder. Design the smallest packet that makes the marked moment inspectable.

markdown
# Bounded Replay Capsule

- schemaVersion:
- markerId:
- sessionId:
- markerCutoffSeq:
- nearbyEventIds:
- console:
- fetch:
- errors:
- manual:
- screenshot:
- dom:
- redaction:

## Boundaries

- included:
- excluded:
- maximum event count:
- privacy rules:

## How To Use It

- agent prompt:
- human review:
- verification command:

App-Specific Marker Flow

An app may wire a shortcut such as Ctrl+M to create durable marker evidence.

Conceptual flow:

snippet-25
Ctrl+M
-> create marker id
-> capture screenshot if available
-> open note/explanation UI
-> save human explanation
-> write durable app logs

Expected log strings:

snippet-26
dev_marker
dev_marker_explanation

Inspection shape:

bash
rg -n "dev_marker|dev_marker_explanation" <app-log-path>/latest-session.jsonl

Keep this generic:

Ask The Agent This

Add markers to a browser bug investigation:

snippet-28
Add agent markers to the checkout browser flow.

Capture console, fetch, errors, and manual markers. Expose
`window.__AGENT_MARKERS__` in dev/test. Add a marker for the moment saved
payment methods disappear after auth refresh. Export JSON and show how to
confirm nearbyEventIds, privacy defaults, and marker explanation.

Turn export into a debug prompt:

snippet-29
Use this agent-marker export as the bounded debug packet.

Focus on the marked checkout failure. Summarize the human explanation, nearby
console/fetch/error/manual evidence, privacy boundaries, and the first
verification command. Do not infer app state that is not in the packet.

Write a test export:

snippet-30
Create a Playwright-style test path that triggers the checkout bug, calls
`window.__AGENT_MARKERS__.mark(...)`, exports the session JSON, and attaches it
as a test artifact. Include the checks that prove marker count, nearbyEventIds,
and event types are present.

What To Confirm / How To Know It Worked

GoalConfirmation
marker client installedapp imports createAgentMarkers
marker createdexport has markers.length > 0
explanation presentmarker has a specific note
nearby evidence linkedmarker has non-empty nearbyEventIds
console capturedexported events include console type
fetch capturedexported events include fetch type
errors capturedexported events include error type
privacy default safestorage values are absent unless deliberately enabled
global test surface workswindow.__AGENT_MARKERS__.export() returns session
export savedJSON artifact exists and is non-empty
cleanup handledstop() called when patching should end
project verifiesnpm test, npm run typecheck, npm run build, npm run smoke:demo

If It Goes Wrong

Marker Has No Note

Add expected/actual context.

snippet-31
What should have happened:
What happened:
Why this moment matters:
Next action:

Export Has Too Many Raw Logs

Focus on one marker id and its nearby events. Increase event limits deliberately, not by default.

nearbyEventIds Is Empty

Mark closer to the failure or adjust the nearby event window.

Sensitive Storage Values Were Captured

Redact and rebuild the export. Capture storage metadata, not values, unless safe and intentional.

Console/Fetch Remains Patched

Call:

ts
markers.stop();

Test Runner Cannot Export

Confirm exposeGlobal: true in dev/test and wait for app readiness before reading window.__AGENT_MARKERS__.

Screenshot Or DOM Hook Is Missing

Mark it unavailable. Do not pretend a screenshot or DOM snapshot exists.

References And Resources