Human testimony joined to runtime evidence — worked example

Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.

Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.

The session, beat by beat

Replayed from a prior scripted session against the workshop's Field Notes demo app — the same run that produced sample-session.json, published raw on this site. Prompts are condensed; every output below is quoted verbatim from the captured artifacts.

You

Serve the Field Notes demo and reproduce the reconnect-and-save failure: type a note, go offline, save, reconnect, save again.

Agent

Drove the app in a scripted browser. The offline save failed honestly ("Save failed (offline?)"). After Reconnect, the second save showed "Saved " — but the mock server returned 401. The plant: reconnecting rotates the server's session token, the client keeps its stale copy, and the save handler treats anything below 500 as success:

// BUG: only 5xx counts as failure, so the stale-token 401 shows "Saved ".
if (res.status < 500) {
  statusEl.textContent = "Saved ";
} else {
  statusEl.textContent = "Save failed (server error)";
}

Would your users file a useful bug report for this? They saw a success message. That gap is the whole reason markers exist.

You

Mark that moment. Testimony: "It said Saved but my note never reached the server — this happened right after I reconnected."

Agent

The button uses prompt(), which blocks scripted browsers — so the mark went in through the console instead:

window.__AGENT_MARKERS__.mark(
  "user-flag",
  "It said Saved but my note never reached the server — this happened right after I reconnected."
)

Marker <demo-marker> recorded, pinned to the nine nearest events by id.

For a human it's one keystroke (Ctrl/Cmd+M) and one sentence at the moment of surprise. No form, no repro steps demanded — anything heavier and nobody uses it when it matters.

You

Export the session and show me exactly what leaves the machine.

Agent

exportSession() produced a schemaVersion-1 JSON — 1 marker, 10 events, and a redaction block that documents what was withheld:

"redaction": {
  "storageValues": "excluded",
  "requestBodies": "excluded",
  "responseBodies": "excluded",
  "userText": "preview+length only"
}

No request or response bodies, no tokens, no storage values; user text travels as preview + length only. The full export is published raw as sample-session.json.

The redaction policy rides inside the payload, so every reader can audit what was withheld. A capture safe enough to paste anywhere gets pasted; a risky one gets hoarded and helps no one.

You

Render the agent packet from that export.

Agent

node scripts/make-agent-packet.mjs samples/sample-session.json

The packet leads with the testimony, then the seq-ordered evidence slice. Seven consecutive lines, exactly as rendered:

- [seq 3 · t+17397ms] click: click <button#save> "Save note"
- [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms]
- [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable
- [seq 6 · t+18436ms] click: click <button#toggle-net> "Reconnect"
- [seq 7 · t+18436ms] console: console.log: reconnected: session restored
- [seq 8 · t+18909ms] click: click <button#save> "Save note"
- [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms]

Read it top to bottom: NETWORK-ERROR → "reconnected" → 401 on the very next save, under a visible "Saved ". A nine-line slice doing what a full log dump rarely does.

You

Now read the packet cold — no source code, no other context. One hypothesis, one sentence, before you look at anything else.

Agent

The reconnect rotated or invalidated a session credential the client still holds, and the app treats the resulting 401 as success.

Flagged as "hypothesis — needs verification", per the packet's claims boundary: testimony is not diagnosis, context is not proof.

That is the pass condition for any capture you build: a cold reader — human or agent — gets from the packet alone to the mechanism. The hypothesis arrives labeled as a draft; a person verifies it against the running app.

You

Good. Give me the version I can drop into any app.

Agent

The whole recorder — dependency-free, no build step. Everything above was captured by these lines (same bytes as agent-markers.js on this site):

/**
 * agent-markers.js — a tiny, dependency-free "press a button, capture the moment" recorder.
 *
 * Pattern: a MARKER is timestamped human testimony ("this moment matters, here's why").
 * A TRAIL is the ordered semantic events (console, fetch, error, click) that led there.
 * Export = bounded, redacted payload you can hand to an agent as a debug packet.
 *
 * Deliberately NOT captured: storage values, request/response bodies, raw input text.
 * Testimony is not diagnosis. Context is not proof.
 */
(function (global) {
  "use strict";

  const state = {
    running: false,
    sessionId: null,
    startedAtIso: null,
    startedAtMs: 0,
    seq: 0,
    events: [],
    markers: [],
    maxEvents: 200,
    nearbyEventLimit: 12,
    restoreFns: [],
  };

  function now() {
    return Math.round(performance.now() - state.startedAtMs);
  }

  function preview(text, max = 80) {
    const s = String(text ?? "");
    return {
      preview: s.length > max ? s.slice(0, max) + "…" : s,
      length: s.length,
      truncated: s.length > max,
    };
  }

  function record(type, data) {
    if (!state.running) return null;
    const event = { id: "evt-" + (++state.seq), seq: state.seq, t: now(), type, data };
    state.events.push(event);
    if (state.events.length > state.maxEvents) state.events.shift();
    return event;
  }

  function patchConsole() {
    ["log", "warn", "error"].forEach((level) => {
      const original = console[level];
      console[level] = function (...args) {
        record("console", { level, message: preview(args.map(String).join(" ")) });
        return original.apply(console, args);
      };
      state.restoreFns.push(() => (console[level] = original));
    });
  }

  function patchFetch() {
    const original = global.fetch;
    global.fetch = async function (input, init) {
      const url = typeof input === "string" ? input : input.url;
      const method = (init && init.method) || "GET";
      const started = now();
      try {
        const res = await original.apply(global, arguments);
        record("fetch", { method, url, status: res.status, ok: res.ok, ms: now() - started });
        return res;
      } catch (error) {
        record("fetch", { method, url, status: null, ok: false, ms: now() - started, error: preview(error && error.message) });
        throw error;
      }
    };
    state.restoreFns.push(() => (global.fetch = original));
  }

  function patchErrors() {
    const onError = (event) =>
      record("error", { message: preview(event.message || String(event.reason || "unknown")) });
    global.addEventListener("error", onError);
    global.addEventListener("unhandledrejection", onError);
    state.restoreFns.push(() => {
      global.removeEventListener("error", onError);
      global.removeEventListener("unhandledrejection", onError);
    });
  }

  function patchClicks() {
    const onClick = (event) => {
      const el = event.target.closest("button, a, [data-action]") || event.target;
      record("click", {
        tag: el.tagName.toLowerCase(),
        id: el.id || null,
        action: el.dataset ? el.dataset.action || null : null,
        text: preview(el.textContent && el.textContent.trim(), 40),
      });
    };
    document.addEventListener("click", onClick, true);
    state.restoreFns.push(() => document.removeEventListener("click", onClick, true));
  }

  const AgentMarkers = {
    start(options = {}) {
      if (state.running) return this;
      state.sessionId = options.sessionId || "session-" + Date.now().toString(36);
      state.startedAtIso = new Date().toISOString();
      state.startedAtMs = performance.now();
      state.maxEvents = options.maxEvents || 200;
      state.nearbyEventLimit = options.nearbyEventLimit || 12;
      state.seq = 0;
      state.events = [];
      state.markers = [];
      state.running = true;
      patchConsole();
      patchFetch();
      patchErrors();
      patchClicks();
      if (options.exposeGlobal !== false) global.__AGENT_MARKERS__ = AgentMarkers;
      record("session", { note: "recording started", app: options.app || "unknown" });
      return this;
    },

    /** Human presses the button: timestamped testimony + pointers into the trail. */
    mark(label, note) {
      if (!state.running) throw new Error("AgentMarkers not started");
      const nearby = state.events.slice(-state.nearbyEventLimit).map((e) => e.id);
      const marker = {
        id: "mrk-" + (state.markers.length + 1) + "-" + Date.now().toString(36),
        seq: ++state.seq,
        t: now(),
        label: label || "unlabeled",
        note: note || "",
        nearbyEventIds: nearby,
        screenshot: "unavailable", // browser demo: no screenshot API without permissions
      };
      state.markers.push(marker);
      record("marker", { markerId: marker.id, label: marker.label });
      return marker;
    },

    record(type, data) {
      return record("manual", { type, ...data });
    },

    /** Bounded, redacted payload — everything an agent gets, nothing more. */
    exportSession() {
      return {
        schemaVersion: 1,
        sessionId: state.sessionId,
        startedAt: state.startedAtIso,
        exportedAt: new Date().toISOString(),
        userAgent: navigator.userAgent,
        markers: state.markers,
        events: state.events,
        redaction: {
          storageValues: "excluded",
          requestBodies: "excluded",
          responseBodies: "excluded",
          userText: "preview+length only",
        },
      };
    },

    stop() {
      state.restoreFns.forEach((restore) => restore());
      state.restoreFns = [];
      state.running = false;
      return this;
    },
  };

  if (typeof module !== "undefined" && module.exports) module.exports = AgentMarkers;
  global.AgentMarkers = AgentMarkers;
})(typeof window !== "undefined" ? window : globalThis);

The boot file and the packet renderer are printed complete in the section guide, or replay this whole loop from an empty directory:

mkdir -p markers-quickstart && cd markers-quickstart
curl -sO https://mindful-mango-accy.here.now/agent-markers.js
curl -sO https://mindful-mango-accy.here.now/make-agent-packet.mjs
curl -sO https://mindful-mango-accy.here.now/sample-session.json
node make-agent-packet.mjs sample-session.json

Total session: five prompts. The loop the transcript demonstrates — mark → export → packet → hypothesis — is the same one your attendees' agents replay from agent.md.

Source references