@plslog/agent-bridge

Local bridge between browser logs and an AI agent.

This package receives structured logs from a browser app over HTTP, keeps them in a small in-memory buffer, and exposes query endpoints an agent can call while debugging. It can be used with plslog, a custom logger, or plain fetch.

Purpose

@plslog/agent-bridge is for development-time debugging workflows where an agent needs runtime evidence from the browser.

It helps the agent answer questions like:

• What errors happened in the browser?
• Which route or page produced the log?
• What happened before the failure?
• Which namespace, session, or tag should be inspected?
• Is the log buffer truncated?

Package Boundary

Use @plslog/agent-bridge when browser/runtime logs need to be captured locally for agent inspection.

It is intentionally not tied to plslog. The bridge accepts HTTP requests, so any app can send logs to it.

The package provides:

• a local HTTP log server
• an optional plslog transport that batches logs to that server
• agent-friendly log fields such as ISO timestamp, source, page context, session id, tags, and serialized errors
• query endpoints for filtering and summaries

Usage

Start the local bridge:

pnpm server

After publishing, run it directly with your package manager:

npx @plslog/agent-bridge

Or install it in a project:

pnpm add -D @plslog/agent-bridge
pnpm exec plslog-agent-bridge

Use a custom port with PORT:

PORT=2222 pnpm exec plslog-agent-bridge

Native Fetch

Drop this anywhere in your app. No client package install is required.

const log = (level, msg, data) =>
  fetch('http://localhost:1111/log', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ level, msg, data, ts: Date.now() }),
  });

log('info', 'Checkout mounted', { cartItems: 3 });

For richer agent context, send the canonical field names:

const log = (level, message, data) =>
  fetch('http://localhost:1111/log', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      level,
      message,
      data,
      timestamp: Date.now(),
      source: 'browser',
      page: {
        url: location.href,
        route: `${location.pathname}${location.search}${location.hash}`,
        title: document.title,
      },
    }),
  });

log('info', 'Checkout mounted', { cartItems: 3 });

The minimum accepted payload is either message or msg:

fetch('http://localhost:1111/log', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    level: 'info',
    msg: 'App started',
  }),
});

For batches:

fetch('http://localhost:1111/logs/batch', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    logs: [
      { level: 'info', msg: 'App started', ts: Date.now() },
      { level: 'error', message: 'Request failed', data: { status: 500 } },
    ],
  }),
});

With plslog

Attach the optional browser transport in development:

import plslog, { LogLevel } from 'plslog';
import { createServerTransport } from '@plslog/agent-bridge/transport';

const isProduction = import.meta.env.PROD;

const transports = !isProduction
  ? [
      createServerTransport(
        import.meta.env.VITE_LOG_SERVER_URL ?? 'http://localhost:1111',
        { batchInterval: 300 }
      ),
    ]
  : [];

plslog.configure({
  activeLevels: ['debug', 'info', 'warn', 'error'] as LogLevel[],
  transports,
});

Endpoints

POST   /log               <- FE client sends one log here
POST   /logs/batch        <- FE client sends batched logs here
GET    /logs              <- Agent reads logs
GET    /logs?level=error  <- Agent filters logs
GET    /logs/summary      <- Agent reads counts and recent errors
DELETE /logs              <- Clear between sessions
GET    /health            <- Check server status

Useful GET /logs filters:

• level=error
• namespace=auth
• source=browser
• sessionId=<id>
• tag=network
• since=<timestamp>
• q=<text>
• limit=100

Notes

This package is not a production observability backend. It stores logs in memory, is optimized for local debugging, and should usually be disabled in production browser builds.

Publishing

Preview the npm package contents:

pnpm pub:dry

Publish manually:

pnpm pub

Run the release flow from the workspace root:

pnpm release:agent-bridge:preview
pnpm release:agent-bridge