logquill 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -1,4 +1,6 @@
-import { createHash } from 'crypto';
+import { randomUUID, randomBytes, createHash } from 'crypto';
+import { AsyncLocalStorage } from 'async_hooks';
+import { createRequire } from 'module';
 import { gzipSync } from 'zlib';
 import { mkdirSync, openSync, writeSync, fstatSync, closeSync, existsSync, unlinkSync, renameSync } from 'fs';
 import { dirname } from 'path';
@@ -80,6 +82,99 @@ var ContextPlugin = class {
     return { ...record, meta: { ...this.context, ...record.meta } };
   }
 };
+var RunPlugin = class {
+  runId;
+  step = 0;
+  constructor(options = {}) {
+    this.runId = options.runId ?? randomUUID();
+  }
+  beforeLog(record) {
+    record.meta.runId ??= this.runId;
+    record.meta.step = this.step++;
+    return record;
+  }
+};
+var traceparentStore = new AsyncLocalStorage();
+function setTraceparent(value) {
+  const previous = traceparentStore.getStore();
+  traceparentStore.enterWith(value);
+  return () => {
+    traceparentStore.enterWith(previous);
+  };
+}
+function getTraceparent() {
+  return traceparentStore.getStore();
+}
+function generateTraceId() {
+  return randomBytes(16).toString("hex");
+}
+var W3C_TRACEPARENT_RE = /^[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/;
+var XRAY_ROOT_RE = /Root=1-([0-9a-f]{8})-([0-9a-f]{24})/;
+var GCP_TRACE_RE = /^([0-9a-f]{32})\/\d+(;o=\d)?$/;
+function parseTraceHeader(header) {
+  const trimmed = header.trim();
+  const w3c = W3C_TRACEPARENT_RE.exec(trimmed);
+  if (w3c?.[1]) {
+    return w3c[1];
+  }
+  const xray = XRAY_ROOT_RE.exec(trimmed);
+  if (xray?.[1] && xray[2]) {
+    return xray[1] + xray[2];
+  }
+  const gcp = GCP_TRACE_RE.exec(trimmed);
+  if (gcp?.[1]) {
+    return gcp[1];
+  }
+  return void 0;
+}
+function defaultResolveActiveOtelTraceId() {
+  try {
+    const require2 = createRequire(import.meta.url);
+    const otel = require2("@opentelemetry/api");
+    const span = otel.trace.getActiveSpan();
+    if (!span) {
+      return void 0;
+    }
+    const spanContext = span.spanContext();
+    if (!otel.trace.isSpanContextValid(spanContext)) {
+      return void 0;
+    }
+    return spanContext.traceId;
+  } catch {
+    return void 0;
+  }
+}
+var TraceContextPlugin = class {
+  traceKey;
+  explicitTraceparent;
+  resolveActiveOtelTraceId;
+  constructor(options = {}) {
+    this.traceKey = options.traceKey ?? "traceId";
+    this.explicitTraceparent = options.traceparent;
+    this.resolveActiveOtelTraceId = options.resolveActiveOtelTraceId ?? defaultResolveActiveOtelTraceId;
+  }
+  beforeLog(record) {
+    if (record.meta[this.traceKey] != null) {
+      return record;
+    }
+    record.meta[this.traceKey] = this.resolveTraceId();
+    return record;
+  }
+  resolveTraceId() {
+    const fromOtel = this.resolveActiveOtelTraceId();
+    if (fromOtel) {
+      return fromOtel;
+    }
+    const header = this.explicitTraceparent ?? getTraceparent();
+    if (header) {
+      const parsed = parseTraceHeader(header);
+      if (parsed) {
+        return parsed;
+      }
+    }
+    return generateTraceId();
+  }
+};
 
 // src/plugins/redact-plugin.ts
 var DEFAULT_REDACTED_KEYS = ["password", "token", "secret", "api_key", "authorization"];
@@ -1708,8 +1803,24 @@ var HTTPTransport = class extends Transport {
     this.flush();
   }
 };
+var spanIdStore = new AsyncLocalStorage();
+function currentSpanId() {
+  return spanIdStore.getStore();
+}
+function newSpanId() {
+  return randomBytes(8).toString("hex");
+}
+function runInSpan(spanId, fn) {
+  return spanIdStore.run(spanId, fn);
+}
 
 // src/core/logger.ts
+function formatSpanError(error) {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return String(error);
+}
 var Logger = class _Logger {
   name;
   transports;
@@ -1773,6 +1884,10 @@ var Logger = class _Logger {
       message,
       meta: { ...this.baseMeta, ...meta }
     });
+    const parentSpanId = currentSpanId();
+    if (parentSpanId !== void 0) {
+      record.meta.parentSpanId ??= parentSpanId;
+    }
     for (const plugin of this.plugins) {
       let result;
       try {
@@ -1787,7 +1902,11 @@ var Logger = class _Logger {
       record = result;
     }
     for (const transport of this.transports) {
-      transport.write(transport.format(record), record);
+      try {
+        transport.write(transport.format(record), record);
+      } catch (error) {
+        console.error(`${transport.constructor.name}: failed to write a log record`, error);
+      }
     }
     for (const plugin of this.plugins) {
       try {
@@ -1816,11 +1935,71 @@ var Logger = class _Logger {
   fatal(message, meta = {}) {
     return this.dispatch(50 /* FATAL */, message, meta);
   }
+  /** `.info()` tagged `meta.kind = "thought"` — an agent's internal reasoning step, for harness/agentic tracing. */
+  thought(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "thought", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "action"` — an agent taking an action (a tool call, an LLM request), for harness/agentic tracing. */
+  action(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "action", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "observation"` — the result an agent observed from an action, for harness/agentic tracing. */
+  observation(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "observation", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "decision"` — an agent's concluding decision for a step or run, for harness/agentic tracing. */
+  decision(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "decision", ...meta });
+  }
+  /**
+   * `await logger.span("callLlm", async () => {...})` — runs `fn`, and on
+   * settling (success or throw) emits one record for the span itself
+   * carrying `meta.spanId` and `meta.durationMs`. Every record logged
+   * inside `fn` — through any method, and through any further `await` —
+   * is automatically stamped with `meta.parentSpanId` pointing at this
+   * span, so nested/sub-agent calls reconstruct their exact nesting when
+   * sorted by `spanId`/`parentSpanId`.
+   *
+   * Still emits its record — at `ERROR`, with `meta.error` set — if `fn`
+   * throws; the error itself propagates unchanged to the caller.
+   *
+   * `spanId`/`parentSpanId` normally auto-generate/auto-nest; pass them in
+   * `options` to adopt an id handed in from elsewhere (e.g. a framework
+   * adapter translating an id it already received).
+   */
+  async span(name, fn, options = {}) {
+    const { spanId: explicitSpanId, parentSpanId: explicitParentSpanId, ...meta } = options;
+    const spanId = explicitSpanId ?? newSpanId();
+    const start = performance.now();
+    try {
+      const result = await runInSpan(spanId, () => fn());
+      this.finishSpan(name, spanId, explicitParentSpanId, performance.now() - start, meta);
+      return result;
+    } catch (error) {
+      this.finishSpan(name, spanId, explicitParentSpanId, performance.now() - start, meta, error);
+      throw error;
+    }
+  }
+  finishSpan(name, spanId, explicitParentSpanId, durationMs, meta, error) {
+    const fullMeta = {
+      spanId,
+      durationMs: Math.round(durationMs * 1e3) / 1e3,
+      ...meta
+    };
+    if (explicitParentSpanId !== void 0) {
+      fullMeta.parentSpanId = explicitParentSpanId;
+    }
+    fullMeta.kind ??= "span";
+    if (error !== void 0) {
+      fullMeta.error = formatSpanError(error);
+    }
+    this.dispatch(error !== void 0 ? 40 /* ERROR */ : 20 /* INFO */, name, fullMeta);
+  }
 };
 
 // src/index.ts
 var VERSION = "0.3.0";
 
-export { AlertingPlugin, AppInsightsTransport, BaseQueueTransport, BaseSQLTransport, BatchingTransport, CloudLoggingTransport, CloudWatchTransport, CollectingTransport, ConsoleTransport, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, DatadogTransport, DynamoDBTransport, ElasticsearchTransport, EmailAlertPlugin, FileTransport, FunctionPlugin, GENESIS_HASH, HTTPTransport, JSONFormatter, KafkaTransport, Level, Logger, MongoDBTransport, MySQLTransport, NewRelicTransport, PIIRedactPlugin, PagerDutyAlertPlugin, PostgresTransport, PubSubTransport, RabbitMQTransport, RedactPlugin, RedisTransport, SQLiteTransport, SQSTransport, SamplingPlugin, SlackAlertPlugin, TamperEvidentPlugin, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };
+export { AlertingPlugin, AppInsightsTransport, BaseQueueTransport, BaseSQLTransport, BatchingTransport, CloudLoggingTransport, CloudWatchTransport, CollectingTransport, ConsoleTransport, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, DatadogTransport, DynamoDBTransport, ElasticsearchTransport, EmailAlertPlugin, FileTransport, FunctionPlugin, GENESIS_HASH, HTTPTransport, JSONFormatter, KafkaTransport, Level, Logger, MongoDBTransport, MySQLTransport, NewRelicTransport, PIIRedactPlugin, PagerDutyAlertPlugin, PostgresTransport, PubSubTransport, RabbitMQTransport, RedactPlugin, RedisTransport, RunPlugin, SQLiteTransport, SQSTransport, SamplingPlugin, SlackAlertPlugin, TamperEvidentPlugin, TraceContextPlugin, Transport, VERSION, createRecord, defaultResolveActiveOtelTraceId, generateTraceId, getTraceparent, levelName, parseLevel, parseTraceHeader, setTraceparent, utcTimestamp };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map