logquill 0.3.0 → 0.4.0

package/dist/langchain.cjs

@@ -0,0 +1,114 @@
+'use strict';
+
+var base = require('@langchain/core/callbacks/base');
+
+// src/adapters/adapter.ts
+var LogQuillAdapter = class {
+  constructor(log) {
+    this.log = log;
+  }
+  log;
+};
+function spanIds(runId, parentRunId) {
+  const ids = { spanId: runId };
+  if (parentRunId !== void 0) {
+    ids.parentSpanId = parentRunId;
+  }
+  return ids;
+}
+function serializedName(serialized, fallback) {
+  const name = serialized?.name;
+  if (typeof name === "string" && name) {
+    return name;
+  }
+  const lastIdSegment = serialized?.id.at(-1);
+  return typeof lastIdSegment === "string" && lastIdSegment ? lastIdSegment : fallback;
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return String(error);
+}
+var LangChainAdapter = class extends base.BaseCallbackHandler {
+  name = "logquill";
+  log;
+  callStarts = /* @__PURE__ */ new Map();
+  chainNames = /* @__PURE__ */ new Map();
+  constructor(agentLog) {
+    super();
+    this.log = agentLog;
+  }
+  takeDurationMs(runId) {
+    const start = this.callStarts.get(runId);
+    if (start === void 0) {
+      return void 0;
+    }
+    this.callStarts.delete(runId);
+    return Math.round((performance.now() - start) * 1e3) / 1e3;
+  }
+  // -- chains: one span()-shaped record on end/error --------------------
+  // `handleChainEnd`/`handleChainError` don't receive the chain's
+  // `Serialized` descriptor (only `handleChainStart` does), so the name is
+  // captured at start and looked up again at end/error.
+  handleChainStart(chain, _inputs, runId) {
+    this.callStarts.set(runId, performance.now());
+    this.chainNames.set(runId, serializedName(chain, "chain"));
+  }
+  handleChainEnd(_outputs, runId, parentRunId) {
+    const name = this.chainNames.get(runId) ?? "chain";
+    this.chainNames.delete(runId);
+    this.log.info(name, { kind: "span", ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });
+  }
+  handleChainError(err, runId, parentRunId) {
+    const name = this.chainNames.get(runId) ?? "chain";
+    this.chainNames.delete(runId);
+    this.log.error(name, {
+      kind: "span",
+      ...spanIds(runId, parentRunId),
+      durationMs: this.takeDurationMs(runId),
+      error: formatError(err)
+    });
+  }
+  // -- LLM calls: action (start) / observation (end) ---------------------
+  handleLLMStart(serialized, _prompts, runId, parentRunId) {
+    this.callStarts.set(runId, performance.now());
+    this.log.action(serializedName(serialized, "llm_start"), spanIds(runId, parentRunId));
+  }
+  handleLLMEnd(_output, runId, parentRunId) {
+    this.log.observation("llm_end", { ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });
+  }
+  handleLLMError(err, runId, parentRunId) {
+    this.takeDurationMs(runId);
+    this.log.error("llm_error", { error: formatError(err), ...spanIds(runId, parentRunId) });
+  }
+  // -- agent-level events --------------------------------------------------
+  handleAgentAction(action, runId) {
+    this.log.action(action.tool || "agent_action", { parentSpanId: runId });
+  }
+  handleAgentEnd(_action, runId) {
+    this.log.decision("agent_finish", { parentSpanId: runId });
+  }
+  // -- tools: action (start) / observation (end) / error -------------------
+  handleToolStart(serialized, _input, runId, parentRunId) {
+    this.callStarts.set(runId, performance.now());
+    this.log.action(serializedName(serialized, "tool"), spanIds(runId, parentRunId));
+  }
+  handleToolEnd(_output, runId, parentRunId) {
+    this.log.observation("tool_end", { ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });
+  }
+  handleToolError(err, runId, parentRunId) {
+    this.takeDurationMs(runId);
+    this.log.error("tool_error", { error: formatError(err), ...spanIds(runId, parentRunId) });
+  }
+};
+
+// src/adapters/langgraph-adapter.ts
+var LangGraphAdapter = class extends LangChainAdapter {
+};
+
+exports.LangChainAdapter = LangChainAdapter;
+exports.LangGraphAdapter = LangGraphAdapter;
+exports.LogQuillAdapter = LogQuillAdapter;
+//# sourceMappingURL=langchain.cjs.map
+//# sourceMappingURL=langchain.cjs.map

package/dist/langchain.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/adapter.ts","../src/adapters/langchain-adapter.ts","../src/adapters/langgraph-adapter.ts"],"names":["BaseCallbackHandler"],"mappings":"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","file":"langchain.cjs","sourcesContent":["import type { Logger } from \"../core/logger.js\";\n\n/**\n * Base for framework tracing adapters. A concrete adapter holds a\n * reference to the `Logger` to forward events onto (`this.log`) and\n * overrides only the events its framework actually emits — translating\n * them into `.thought()/.action()/.observation()/.decision()` calls and\n * `span()`-shaped records. Always a thin mapping from the framework's\n * native event shape onto LogQuill's, never a reimplementation of tracing\n * logic per framework.\n *\n * `LangChainAdapter` doesn't literally extend this: it has to extend\n * LangChain's own `BaseCallbackHandler` instead (JS classes support only\n * single inheritance), so it holds the same `log` reference itself rather\n * than inheriting it. This base is for adapters that don't need to\n * subclass a framework SDK class.\n */\nexport abstract class LogQuillAdapter {\n  constructor(protected readonly log: Logger) {}\n}\n","import { BaseCallbackHandler } from \"@langchain/core/callbacks/base\";\nimport type { AgentAction, AgentFinish } from \"@langchain/core/agents\";\nimport type { Serialized } from \"@langchain/core/load/serializable\";\nimport type { LLMResult } from \"@langchain/core/outputs\";\nimport type { ChainValues } from \"@langchain/core/utils/types\";\nimport type { Logger } from \"../core/logger.js\";\n\nfunction spanIds(runId: string, parentRunId: string | undefined): Record<string, unknown> {\n  const ids: Record<string, unknown> = { spanId: runId };\n  if (parentRunId !== undefined) {\n    ids.parentSpanId = parentRunId;\n  }\n  return ids;\n}\n\n/**\n * Prefers `serialized.name`, which most `Serialized` variants carry — but\n * a bare `RunnableLambda` (and other constructless runnables), verified\n * against `@langchain/core` 1.2.9, omits it. `id` (e.g.\n * `[\"langchain_core\", \"runnables\", \"RunnableLambda\"]`) is present on\n * every `Serialized` variant, so its last segment — the class name — is a\n * more useful fallback than the generic `fallback` string.\n */\nfunction serializedName(serialized: Serialized | undefined, fallback: string): string {\n  const name = (serialized as { name?: unknown } | undefined)?.name;\n  if (typeof name === \"string\" && name) {\n    return name;\n  }\n  const lastIdSegment = serialized?.id.at(-1);\n  return typeof lastIdSegment === \"string\" && lastIdSegment ? lastIdSegment : fallback;\n}\n\n// LangChain's `handle*Error` callbacks type their `error` parameter as\n// `Error` (really `any` in the base class — see `type Error = any` in\n// `@langchain/core`'s own `callbacks/base.d.ts`), but nothing enforces that\n// at the actual throw site: a tool's `_call`, an LLM provider, or any\n// chain step can `throw` a bare string or plain object just as validly.\n// Trusting `Error` here would crash this adapter's own error handler on\n// exactly the input it exists to report.\nfunction formatError(error: unknown): string {\n  if (error instanceof Error) {\n    return `${error.name}: ${error.message}`;\n  }\n  return String(error);\n}\n\n/**\n * Maps LangChain.js's `BaseCallbackHandler` events onto LogQuill calls —\n * LangGraph.js is covered for free (see `LangGraphAdapter`), since it\n * shares LangChain.js's callback system.\n *\n * Pass an instance into a chain/agent invocation's `callbacks: [...]`, the\n * same way any other LangChain tracing handler (LangSmith, Langfuse, ...)\n * is wired in — no other instrumentation needed:\n *\n * ```ts\n * import { Logger, RunPlugin } from \"logquill\";\n * import { LangChainAdapter } from \"logquill/langchain\";\n *\n * const handler = new LangChainAdapter(log.child(\"agent\").use(new RunPlugin()));\n * const llm = new ChatOpenAI({ callbacks: [handler] });\n * ```\n *\n * Event mapping:\n *\n * | LangChain.js callback | LogQuill call |\n * |---|---|\n * | `handleChainStart` / `handleChainEnd` | one `span()`-shaped record on end/error |\n * | `handleLLMStart` / `handleLLMEnd` | `.action()` / `.observation()` with `durationMs` |\n * | `handleAgentAction` | `.action()` |\n * | `handleAgentEnd` | `.decision()` |\n * | `handleToolStart` / `handleToolEnd` / `handleToolError` | `.action()` / `.observation()` / `.error()` |\n *\n * LangChain's own `runId`/`parentRunId` are written directly onto\n * `meta.spanId`/`meta.parentSpanId` on every event — the shapes already\n * match, so this is field renaming, not translation. Chain start/end is\n * stamped manually (rather than via `Logger.span()`, which wraps a single\n * callback) into the same `{ kind: \"span\", spanId, parentSpanId,\n * durationMs }` shape `Logger.span()` itself produces, since LangChain\n * opens and closes a chain run from two separate, independently-scheduled\n * callback invocations — there's no single function to wrap.\n *\n * `handleAgentAction`/`handleAgentEnd` carry the *enclosing* chain's own\n * `runId` (LangChain doesn't mint a fresh one for these events), so it's\n * written as this record's `parentSpanId`, not `spanId` — using it as\n * `spanId` would make the record indistinguishable from the chain's own\n * span-closing record.\n */\nexport class LangChainAdapter extends BaseCallbackHandler {\n  name = \"logquill\";\n\n  private readonly log: Logger;\n  private readonly callStarts = new Map<string, number>();\n  private readonly chainNames = new Map<string, string>();\n\n  constructor(agentLog: Logger) {\n    super();\n    this.log = agentLog;\n  }\n\n  private takeDurationMs(runId: string): number | undefined {\n    const start = this.callStarts.get(runId);\n    if (start === undefined) {\n      return undefined;\n    }\n    this.callStarts.delete(runId);\n    return Math.round((performance.now() - start) * 1000) / 1000;\n  }\n\n  // -- chains: one span()-shaped record on end/error --------------------\n  // `handleChainEnd`/`handleChainError` don't receive the chain's\n  // `Serialized` descriptor (only `handleChainStart` does), so the name is\n  // captured at start and looked up again at end/error.\n\n  handleChainStart(chain: Serialized, _inputs: ChainValues, runId: string): void {\n    this.callStarts.set(runId, performance.now());\n    this.chainNames.set(runId, serializedName(chain, \"chain\"));\n  }\n\n  handleChainEnd(_outputs: ChainValues, runId: string, parentRunId: string | undefined): void {\n    const name = this.chainNames.get(runId) ?? \"chain\";\n    this.chainNames.delete(runId);\n    this.log.info(name, { kind: \"span\", ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });\n  }\n\n  handleChainError(err: unknown, runId: string, parentRunId: string | undefined): void {\n    const name = this.chainNames.get(runId) ?? \"chain\";\n    this.chainNames.delete(runId);\n    this.log.error(name, {\n      kind: \"span\",\n      ...spanIds(runId, parentRunId),\n      durationMs: this.takeDurationMs(runId),\n      error: formatError(err),\n    });\n  }\n\n  // -- LLM calls: action (start) / observation (end) ---------------------\n\n  handleLLMStart(\n    serialized: Serialized,\n    _prompts: string[],\n    runId: string,\n    parentRunId?: string,\n  ): void {\n    this.callStarts.set(runId, performance.now());\n    this.log.action(serializedName(serialized, \"llm_start\"), spanIds(runId, parentRunId));\n  }\n\n  handleLLMEnd(_output: LLMResult, runId: string, parentRunId: string | undefined): void {\n    this.log.observation(\"llm_end\", { ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });\n  }\n\n  handleLLMError(err: unknown, runId: string, parentRunId: string | undefined): void {\n    this.takeDurationMs(runId);\n    this.log.error(\"llm_error\", { error: formatError(err), ...spanIds(runId, parentRunId) });\n  }\n\n  // -- agent-level events --------------------------------------------------\n\n  handleAgentAction(action: AgentAction, runId: string): void {\n    this.log.action(action.tool || \"agent_action\", { parentSpanId: runId });\n  }\n\n  handleAgentEnd(_action: AgentFinish, runId: string): void {\n    this.log.decision(\"agent_finish\", { parentSpanId: runId });\n  }\n\n  // -- tools: action (start) / observation (end) / error -------------------\n\n  handleToolStart(\n    serialized: Serialized,\n    _input: string,\n    runId: string,\n    parentRunId?: string,\n  ): void {\n    this.callStarts.set(runId, performance.now());\n    this.log.action(serializedName(serialized, \"tool\"), spanIds(runId, parentRunId));\n  }\n\n  handleToolEnd(_output: unknown, runId: string, parentRunId: string | undefined): void {\n    this.log.observation(\"tool_end\", { ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });\n  }\n\n  handleToolError(err: unknown, runId: string, parentRunId: string | undefined): void {\n    this.takeDurationMs(runId);\n    this.log.error(\"tool_error\", { error: formatError(err), ...spanIds(runId, parentRunId) });\n  }\n}\n","import { LangChainAdapter } from \"./langchain-adapter.js\";\n\n/**\n * `LangChainAdapter`, for use with LangGraph.js graphs — exported under its\n * own name for discoverability and parity with `logquill-python`'s\n * `LangGraphAdapter`. LangGraph.js nodes run as ordinary LangChain.js\n * `Runnable`s, so `LangChainAdapter`'s `handleChainStart`/`handleLLMStart`/\n * `handleToolStart`/etc. already fire exactly as they would for a plain\n * chain — no extra mapping needed.\n *\n * Unlike `logquill-python`, this class adds no extra event handling.\n * Python's `LangGraphAdapter` exists specifically to catch LangGraph\n * Python's own checkpoint pause/resume events (`on_interrupt`/`on_resume`),\n * which that ecosystem dispatches only to handlers implementing its own\n * `GraphCallbackHandler` — a plain `BaseCallbackHandler` subclass never\n * receives them there. LangGraph.js has no equivalent: as of `@langchain/\n * langgraph` 1.x it exposes no distinct callback-handler class or\n * `onInterrupt`/`onResume` hook — an `interrupt()` call instead pauses the\n * graph and surfaces in its state/stream output (under `__interrupt__`),\n * not through the callback-handler system at all. There is nothing this\n * class could subscribe to that `LangChainAdapter` doesn't already cover.\n *\n * ```ts\n * import { Logger, RunPlugin } from \"logquill\";\n * import { LangGraphAdapter } from \"logquill/langchain\";\n *\n * const handler = new LangGraphAdapter(log.child(\"agent\").use(new RunPlugin()));\n * const graph = builder.compile({ checkpointer });\n * await graph.invoke(input, { callbacks: [handler], configurable: { thread_id: \"1\" } });\n * ```\n */\nexport class LangGraphAdapter extends LangChainAdapter {}\n"]}

package/dist/langchain.d.cts

@@ -0,0 +1,122 @@
+import { d as Logger } from './logger-D1_THnBJ.cjs';
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { AgentAction, AgentFinish } from '@langchain/core/agents';
+import { Serialized } from '@langchain/core/load/serializable';
+import { LLMResult } from '@langchain/core/outputs';
+import { ChainValues } from '@langchain/core/utils/types';
+
+/**
+ * Base for framework tracing adapters. A concrete adapter holds a
+ * reference to the `Logger` to forward events onto (`this.log`) and
+ * overrides only the events its framework actually emits — translating
+ * them into `.thought()/.action()/.observation()/.decision()` calls and
+ * `span()`-shaped records. Always a thin mapping from the framework's
+ * native event shape onto LogQuill's, never a reimplementation of tracing
+ * logic per framework.
+ *
+ * `LangChainAdapter` doesn't literally extend this: it has to extend
+ * LangChain's own `BaseCallbackHandler` instead (JS classes support only
+ * single inheritance), so it holds the same `log` reference itself rather
+ * than inheriting it. This base is for adapters that don't need to
+ * subclass a framework SDK class.
+ */
+declare abstract class LogQuillAdapter {
+    protected readonly log: Logger;
+    constructor(log: Logger);
+}
+
+/**
+ * Maps LangChain.js's `BaseCallbackHandler` events onto LogQuill calls —
+ * LangGraph.js is covered for free (see `LangGraphAdapter`), since it
+ * shares LangChain.js's callback system.
+ *
+ * Pass an instance into a chain/agent invocation's `callbacks: [...]`, the
+ * same way any other LangChain tracing handler (LangSmith, Langfuse, ...)
+ * is wired in — no other instrumentation needed:
+ *
+ * ```ts
+ * import { Logger, RunPlugin } from "logquill";
+ * import { LangChainAdapter } from "logquill/langchain";
+ *
+ * const handler = new LangChainAdapter(log.child("agent").use(new RunPlugin()));
+ * const llm = new ChatOpenAI({ callbacks: [handler] });
+ * ```
+ *
+ * Event mapping:
+ *
+ * | LangChain.js callback | LogQuill call |
+ * |---|---|
+ * | `handleChainStart` / `handleChainEnd` | one `span()`-shaped record on end/error |
+ * | `handleLLMStart` / `handleLLMEnd` | `.action()` / `.observation()` with `durationMs` |
+ * | `handleAgentAction` | `.action()` |
+ * | `handleAgentEnd` | `.decision()` |
+ * | `handleToolStart` / `handleToolEnd` / `handleToolError` | `.action()` / `.observation()` / `.error()` |
+ *
+ * LangChain's own `runId`/`parentRunId` are written directly onto
+ * `meta.spanId`/`meta.parentSpanId` on every event — the shapes already
+ * match, so this is field renaming, not translation. Chain start/end is
+ * stamped manually (rather than via `Logger.span()`, which wraps a single
+ * callback) into the same `{ kind: "span", spanId, parentSpanId,
+ * durationMs }` shape `Logger.span()` itself produces, since LangChain
+ * opens and closes a chain run from two separate, independently-scheduled
+ * callback invocations — there's no single function to wrap.
+ *
+ * `handleAgentAction`/`handleAgentEnd` carry the *enclosing* chain's own
+ * `runId` (LangChain doesn't mint a fresh one for these events), so it's
+ * written as this record's `parentSpanId`, not `spanId` — using it as
+ * `spanId` would make the record indistinguishable from the chain's own
+ * span-closing record.
+ */
+declare class LangChainAdapter extends BaseCallbackHandler {
+    name: string;
+    private readonly log;
+    private readonly callStarts;
+    private readonly chainNames;
+    constructor(agentLog: Logger);
+    private takeDurationMs;
+    handleChainStart(chain: Serialized, _inputs: ChainValues, runId: string): void;
+    handleChainEnd(_outputs: ChainValues, runId: string, parentRunId: string | undefined): void;
+    handleChainError(err: unknown, runId: string, parentRunId: string | undefined): void;
+    handleLLMStart(serialized: Serialized, _prompts: string[], runId: string, parentRunId?: string): void;
+    handleLLMEnd(_output: LLMResult, runId: string, parentRunId: string | undefined): void;
+    handleLLMError(err: unknown, runId: string, parentRunId: string | undefined): void;
+    handleAgentAction(action: AgentAction, runId: string): void;
+    handleAgentEnd(_action: AgentFinish, runId: string): void;
+    handleToolStart(serialized: Serialized, _input: string, runId: string, parentRunId?: string): void;
+    handleToolEnd(_output: unknown, runId: string, parentRunId: string | undefined): void;
+    handleToolError(err: unknown, runId: string, parentRunId: string | undefined): void;
+}
+
+/**
+ * `LangChainAdapter`, for use with LangGraph.js graphs — exported under its
+ * own name for discoverability and parity with `logquill-python`'s
+ * `LangGraphAdapter`. LangGraph.js nodes run as ordinary LangChain.js
+ * `Runnable`s, so `LangChainAdapter`'s `handleChainStart`/`handleLLMStart`/
+ * `handleToolStart`/etc. already fire exactly as they would for a plain
+ * chain — no extra mapping needed.
+ *
+ * Unlike `logquill-python`, this class adds no extra event handling.
+ * Python's `LangGraphAdapter` exists specifically to catch LangGraph
+ * Python's own checkpoint pause/resume events (`on_interrupt`/`on_resume`),
+ * which that ecosystem dispatches only to handlers implementing its own
+ * `GraphCallbackHandler` — a plain `BaseCallbackHandler` subclass never
+ * receives them there. LangGraph.js has no equivalent: as of `@langchain/
+ * langgraph` 1.x it exposes no distinct callback-handler class or
+ * `onInterrupt`/`onResume` hook — an `interrupt()` call instead pauses the
+ * graph and surfaces in its state/stream output (under `__interrupt__`),
+ * not through the callback-handler system at all. There is nothing this
+ * class could subscribe to that `LangChainAdapter` doesn't already cover.
+ *
+ * ```ts
+ * import { Logger, RunPlugin } from "logquill";
+ * import { LangGraphAdapter } from "logquill/langchain";
+ *
+ * const handler = new LangGraphAdapter(log.child("agent").use(new RunPlugin()));
+ * const graph = builder.compile({ checkpointer });
+ * await graph.invoke(input, { callbacks: [handler], configurable: { thread_id: "1" } });
+ * ```
+ */
+declare class LangGraphAdapter extends LangChainAdapter {
+}
+
+export { LangChainAdapter, LangGraphAdapter, LogQuillAdapter };

package/dist/langchain.d.ts

@@ -0,0 +1,122 @@
+import { d as Logger } from './logger-D1_THnBJ.js';
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { AgentAction, AgentFinish } from '@langchain/core/agents';
+import { Serialized } from '@langchain/core/load/serializable';
+import { LLMResult } from '@langchain/core/outputs';
+import { ChainValues } from '@langchain/core/utils/types';
+
+/**
+ * Base for framework tracing adapters. A concrete adapter holds a
+ * reference to the `Logger` to forward events onto (`this.log`) and
+ * overrides only the events its framework actually emits — translating
+ * them into `.thought()/.action()/.observation()/.decision()` calls and
+ * `span()`-shaped records. Always a thin mapping from the framework's
+ * native event shape onto LogQuill's, never a reimplementation of tracing
+ * logic per framework.
+ *
+ * `LangChainAdapter` doesn't literally extend this: it has to extend
+ * LangChain's own `BaseCallbackHandler` instead (JS classes support only
+ * single inheritance), so it holds the same `log` reference itself rather
+ * than inheriting it. This base is for adapters that don't need to
+ * subclass a framework SDK class.
+ */
+declare abstract class LogQuillAdapter {
+    protected readonly log: Logger;
+    constructor(log: Logger);
+}
+
+/**
+ * Maps LangChain.js's `BaseCallbackHandler` events onto LogQuill calls —
+ * LangGraph.js is covered for free (see `LangGraphAdapter`), since it
+ * shares LangChain.js's callback system.
+ *
+ * Pass an instance into a chain/agent invocation's `callbacks: [...]`, the
+ * same way any other LangChain tracing handler (LangSmith, Langfuse, ...)
+ * is wired in — no other instrumentation needed:
+ *
+ * ```ts
+ * import { Logger, RunPlugin } from "logquill";
+ * import { LangChainAdapter } from "logquill/langchain";
+ *
+ * const handler = new LangChainAdapter(log.child("agent").use(new RunPlugin()));
+ * const llm = new ChatOpenAI({ callbacks: [handler] });
+ * ```
+ *
+ * Event mapping:
+ *
+ * | LangChain.js callback | LogQuill call |
+ * |---|---|
+ * | `handleChainStart` / `handleChainEnd` | one `span()`-shaped record on end/error |
+ * | `handleLLMStart` / `handleLLMEnd` | `.action()` / `.observation()` with `durationMs` |
+ * | `handleAgentAction` | `.action()` |
+ * | `handleAgentEnd` | `.decision()` |
+ * | `handleToolStart` / `handleToolEnd` / `handleToolError` | `.action()` / `.observation()` / `.error()` |
+ *
+ * LangChain's own `runId`/`parentRunId` are written directly onto
+ * `meta.spanId`/`meta.parentSpanId` on every event — the shapes already
+ * match, so this is field renaming, not translation. Chain start/end is
+ * stamped manually (rather than via `Logger.span()`, which wraps a single
+ * callback) into the same `{ kind: "span", spanId, parentSpanId,
+ * durationMs }` shape `Logger.span()` itself produces, since LangChain
+ * opens and closes a chain run from two separate, independently-scheduled
+ * callback invocations — there's no single function to wrap.
+ *
+ * `handleAgentAction`/`handleAgentEnd` carry the *enclosing* chain's own
+ * `runId` (LangChain doesn't mint a fresh one for these events), so it's
+ * written as this record's `parentSpanId`, not `spanId` — using it as
+ * `spanId` would make the record indistinguishable from the chain's own
+ * span-closing record.
+ */
+declare class LangChainAdapter extends BaseCallbackHandler {
+    name: string;
+    private readonly log;
+    private readonly callStarts;
+    private readonly chainNames;
+    constructor(agentLog: Logger);
+    private takeDurationMs;
+    handleChainStart(chain: Serialized, _inputs: ChainValues, runId: string): void;
+    handleChainEnd(_outputs: ChainValues, runId: string, parentRunId: string | undefined): void;
+    handleChainError(err: unknown, runId: string, parentRunId: string | undefined): void;
+    handleLLMStart(serialized: Serialized, _prompts: string[], runId: string, parentRunId?: string): void;
+    handleLLMEnd(_output: LLMResult, runId: string, parentRunId: string | undefined): void;
+    handleLLMError(err: unknown, runId: string, parentRunId: string | undefined): void;
+    handleAgentAction(action: AgentAction, runId: string): void;
+    handleAgentEnd(_action: AgentFinish, runId: string): void;
+    handleToolStart(serialized: Serialized, _input: string, runId: string, parentRunId?: string): void;
+    handleToolEnd(_output: unknown, runId: string, parentRunId: string | undefined): void;
+    handleToolError(err: unknown, runId: string, parentRunId: string | undefined): void;
+}
+
+/**
+ * `LangChainAdapter`, for use with LangGraph.js graphs — exported under its
+ * own name for discoverability and parity with `logquill-python`'s
+ * `LangGraphAdapter`. LangGraph.js nodes run as ordinary LangChain.js
+ * `Runnable`s, so `LangChainAdapter`'s `handleChainStart`/`handleLLMStart`/
+ * `handleToolStart`/etc. already fire exactly as they would for a plain
+ * chain — no extra mapping needed.
+ *
+ * Unlike `logquill-python`, this class adds no extra event handling.
+ * Python's `LangGraphAdapter` exists specifically to catch LangGraph
+ * Python's own checkpoint pause/resume events (`on_interrupt`/`on_resume`),
+ * which that ecosystem dispatches only to handlers implementing its own
+ * `GraphCallbackHandler` — a plain `BaseCallbackHandler` subclass never
+ * receives them there. LangGraph.js has no equivalent: as of `@langchain/
+ * langgraph` 1.x it exposes no distinct callback-handler class or
+ * `onInterrupt`/`onResume` hook — an `interrupt()` call instead pauses the
+ * graph and surfaces in its state/stream output (under `__interrupt__`),
+ * not through the callback-handler system at all. There is nothing this
+ * class could subscribe to that `LangChainAdapter` doesn't already cover.
+ *
+ * ```ts
+ * import { Logger, RunPlugin } from "logquill";
+ * import { LangGraphAdapter } from "logquill/langchain";
+ *
+ * const handler = new LangGraphAdapter(log.child("agent").use(new RunPlugin()));
+ * const graph = builder.compile({ checkpointer });
+ * await graph.invoke(input, { callbacks: [handler], configurable: { thread_id: "1" } });
+ * ```
+ */
+declare class LangGraphAdapter extends LangChainAdapter {
+}
+
+export { LangChainAdapter, LangGraphAdapter, LogQuillAdapter };

package/dist/langchain.mjs

@@ -0,0 +1,110 @@
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+
+// src/adapters/adapter.ts
+var LogQuillAdapter = class {
+  constructor(log) {
+    this.log = log;
+  }
+  log;
+};
+function spanIds(runId, parentRunId) {
+  const ids = { spanId: runId };
+  if (parentRunId !== void 0) {
+    ids.parentSpanId = parentRunId;
+  }
+  return ids;
+}
+function serializedName(serialized, fallback) {
+  const name = serialized?.name;
+  if (typeof name === "string" && name) {
+    return name;
+  }
+  const lastIdSegment = serialized?.id.at(-1);
+  return typeof lastIdSegment === "string" && lastIdSegment ? lastIdSegment : fallback;
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return String(error);
+}
+var LangChainAdapter = class extends BaseCallbackHandler {
+  name = "logquill";
+  log;
+  callStarts = /* @__PURE__ */ new Map();
+  chainNames = /* @__PURE__ */ new Map();
+  constructor(agentLog) {
+    super();
+    this.log = agentLog;
+  }
+  takeDurationMs(runId) {
+    const start = this.callStarts.get(runId);
+    if (start === void 0) {
+      return void 0;
+    }
+    this.callStarts.delete(runId);
+    return Math.round((performance.now() - start) * 1e3) / 1e3;
+  }
+  // -- chains: one span()-shaped record on end/error --------------------
+  // `handleChainEnd`/`handleChainError` don't receive the chain's
+  // `Serialized` descriptor (only `handleChainStart` does), so the name is
+  // captured at start and looked up again at end/error.
+  handleChainStart(chain, _inputs, runId) {
+    this.callStarts.set(runId, performance.now());
+    this.chainNames.set(runId, serializedName(chain, "chain"));
+  }
+  handleChainEnd(_outputs, runId, parentRunId) {
+    const name = this.chainNames.get(runId) ?? "chain";
+    this.chainNames.delete(runId);
+    this.log.info(name, { kind: "span", ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });
+  }
+  handleChainError(err, runId, parentRunId) {
+    const name = this.chainNames.get(runId) ?? "chain";
+    this.chainNames.delete(runId);
+    this.log.error(name, {
+      kind: "span",
+      ...spanIds(runId, parentRunId),
+      durationMs: this.takeDurationMs(runId),
+      error: formatError(err)
+    });
+  }
+  // -- LLM calls: action (start) / observation (end) ---------------------
+  handleLLMStart(serialized, _prompts, runId, parentRunId) {
+    this.callStarts.set(runId, performance.now());
+    this.log.action(serializedName(serialized, "llm_start"), spanIds(runId, parentRunId));
+  }
+  handleLLMEnd(_output, runId, parentRunId) {
+    this.log.observation("llm_end", { ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });
+  }
+  handleLLMError(err, runId, parentRunId) {
+    this.takeDurationMs(runId);
+    this.log.error("llm_error", { error: formatError(err), ...spanIds(runId, parentRunId) });
+  }
+  // -- agent-level events --------------------------------------------------
+  handleAgentAction(action, runId) {
+    this.log.action(action.tool || "agent_action", { parentSpanId: runId });
+  }
+  handleAgentEnd(_action, runId) {
+    this.log.decision("agent_finish", { parentSpanId: runId });
+  }
+  // -- tools: action (start) / observation (end) / error -------------------
+  handleToolStart(serialized, _input, runId, parentRunId) {
+    this.callStarts.set(runId, performance.now());
+    this.log.action(serializedName(serialized, "tool"), spanIds(runId, parentRunId));
+  }
+  handleToolEnd(_output, runId, parentRunId) {
+    this.log.observation("tool_end", { ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });
+  }
+  handleToolError(err, runId, parentRunId) {
+    this.takeDurationMs(runId);
+    this.log.error("tool_error", { error: formatError(err), ...spanIds(runId, parentRunId) });
+  }
+};
+
+// src/adapters/langgraph-adapter.ts
+var LangGraphAdapter = class extends LangChainAdapter {
+};
+
+export { LangChainAdapter, LangGraphAdapter, LogQuillAdapter };
+//# sourceMappingURL=langchain.mjs.map
+//# sourceMappingURL=langchain.mjs.map

package/dist/langchain.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/adapter.ts","../src/adapters/langchain-adapter.ts","../src/adapters/langgraph-adapter.ts"],"names":[],"mappings":"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","file":"langchain.mjs","sourcesContent":["import type { Logger } from \"../core/logger.js\";\n\n/**\n * Base for framework tracing adapters. A concrete adapter holds a\n * reference to the `Logger` to forward events onto (`this.log`) and\n * overrides only the events its framework actually emits — translating\n * them into `.thought()/.action()/.observation()/.decision()` calls and\n * `span()`-shaped records. Always a thin mapping from the framework's\n * native event shape onto LogQuill's, never a reimplementation of tracing\n * logic per framework.\n *\n * `LangChainAdapter` doesn't literally extend this: it has to extend\n * LangChain's own `BaseCallbackHandler` instead (JS classes support only\n * single inheritance), so it holds the same `log` reference itself rather\n * than inheriting it. This base is for adapters that don't need to\n * subclass a framework SDK class.\n */\nexport abstract class LogQuillAdapter {\n  constructor(protected readonly log: Logger) {}\n}\n","import { BaseCallbackHandler } from \"@langchain/core/callbacks/base\";\nimport type { AgentAction, AgentFinish } from \"@langchain/core/agents\";\nimport type { Serialized } from \"@langchain/core/load/serializable\";\nimport type { LLMResult } from \"@langchain/core/outputs\";\nimport type { ChainValues } from \"@langchain/core/utils/types\";\nimport type { Logger } from \"../core/logger.js\";\n\nfunction spanIds(runId: string, parentRunId: string | undefined): Record<string, unknown> {\n  const ids: Record<string, unknown> = { spanId: runId };\n  if (parentRunId !== undefined) {\n    ids.parentSpanId = parentRunId;\n  }\n  return ids;\n}\n\n/**\n * Prefers `serialized.name`, which most `Serialized` variants carry — but\n * a bare `RunnableLambda` (and other constructless runnables), verified\n * against `@langchain/core` 1.2.9, omits it. `id` (e.g.\n * `[\"langchain_core\", \"runnables\", \"RunnableLambda\"]`) is present on\n * every `Serialized` variant, so its last segment — the class name — is a\n * more useful fallback than the generic `fallback` string.\n */\nfunction serializedName(serialized: Serialized | undefined, fallback: string): string {\n  const name = (serialized as { name?: unknown } | undefined)?.name;\n  if (typeof name === \"string\" && name) {\n    return name;\n  }\n  const lastIdSegment = serialized?.id.at(-1);\n  return typeof lastIdSegment === \"string\" && lastIdSegment ? lastIdSegment : fallback;\n}\n\n// LangChain's `handle*Error` callbacks type their `error` parameter as\n// `Error` (really `any` in the base class — see `type Error = any` in\n// `@langchain/core`'s own `callbacks/base.d.ts`), but nothing enforces that\n// at the actual throw site: a tool's `_call`, an LLM provider, or any\n// chain step can `throw` a bare string or plain object just as validly.\n// Trusting `Error` here would crash this adapter's own error handler on\n// exactly the input it exists to report.\nfunction formatError(error: unknown): string {\n  if (error instanceof Error) {\n    return `${error.name}: ${error.message}`;\n  }\n  return String(error);\n}\n\n/**\n * Maps LangChain.js's `BaseCallbackHandler` events onto LogQuill calls —\n * LangGraph.js is covered for free (see `LangGraphAdapter`), since it\n * shares LangChain.js's callback system.\n *\n * Pass an instance into a chain/agent invocation's `callbacks: [...]`, the\n * same way any other LangChain tracing handler (LangSmith, Langfuse, ...)\n * is wired in — no other instrumentation needed:\n *\n * ```ts\n * import { Logger, RunPlugin } from \"logquill\";\n * import { LangChainAdapter } from \"logquill/langchain\";\n *\n * const handler = new LangChainAdapter(log.child(\"agent\").use(new RunPlugin()));\n * const llm = new ChatOpenAI({ callbacks: [handler] });\n * ```\n *\n * Event mapping:\n *\n * | LangChain.js callback | LogQuill call |\n * |---|---|\n * | `handleChainStart` / `handleChainEnd` | one `span()`-shaped record on end/error |\n * | `handleLLMStart` / `handleLLMEnd` | `.action()` / `.observation()` with `durationMs` |\n * | `handleAgentAction` | `.action()` |\n * | `handleAgentEnd` | `.decision()` |\n * | `handleToolStart` / `handleToolEnd` / `handleToolError` | `.action()` / `.observation()` / `.error()` |\n *\n * LangChain's own `runId`/`parentRunId` are written directly onto\n * `meta.spanId`/`meta.parentSpanId` on every event — the shapes already\n * match, so this is field renaming, not translation. Chain start/end is\n * stamped manually (rather than via `Logger.span()`, which wraps a single\n * callback) into the same `{ kind: \"span\", spanId, parentSpanId,\n * durationMs }` shape `Logger.span()` itself produces, since LangChain\n * opens and closes a chain run from two separate, independently-scheduled\n * callback invocations — there's no single function to wrap.\n *\n * `handleAgentAction`/`handleAgentEnd` carry the *enclosing* chain's own\n * `runId` (LangChain doesn't mint a fresh one for these events), so it's\n * written as this record's `parentSpanId`, not `spanId` — using it as\n * `spanId` would make the record indistinguishable from the chain's own\n * span-closing record.\n */\nexport class LangChainAdapter extends BaseCallbackHandler {\n  name = \"logquill\";\n\n  private readonly log: Logger;\n  private readonly callStarts = new Map<string, number>();\n  private readonly chainNames = new Map<string, string>();\n\n  constructor(agentLog: Logger) {\n    super();\n    this.log = agentLog;\n  }\n\n  private takeDurationMs(runId: string): number | undefined {\n    const start = this.callStarts.get(runId);\n    if (start === undefined) {\n      return undefined;\n    }\n    this.callStarts.delete(runId);\n    return Math.round((performance.now() - start) * 1000) / 1000;\n  }\n\n  // -- chains: one span()-shaped record on end/error --------------------\n  // `handleChainEnd`/`handleChainError` don't receive the chain's\n  // `Serialized` descriptor (only `handleChainStart` does), so the name is\n  // captured at start and looked up again at end/error.\n\n  handleChainStart(chain: Serialized, _inputs: ChainValues, runId: string): void {\n    this.callStarts.set(runId, performance.now());\n    this.chainNames.set(runId, serializedName(chain, \"chain\"));\n  }\n\n  handleChainEnd(_outputs: ChainValues, runId: string, parentRunId: string | undefined): void {\n    const name = this.chainNames.get(runId) ?? \"chain\";\n    this.chainNames.delete(runId);\n    this.log.info(name, { kind: \"span\", ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });\n  }\n\n  handleChainError(err: unknown, runId: string, parentRunId: string | undefined): void {\n    const name = this.chainNames.get(runId) ?? \"chain\";\n    this.chainNames.delete(runId);\n    this.log.error(name, {\n      kind: \"span\",\n      ...spanIds(runId, parentRunId),\n      durationMs: this.takeDurationMs(runId),\n      error: formatError(err),\n    });\n  }\n\n  // -- LLM calls: action (start) / observation (end) ---------------------\n\n  handleLLMStart(\n    serialized: Serialized,\n    _prompts: string[],\n    runId: string,\n    parentRunId?: string,\n  ): void {\n    this.callStarts.set(runId, performance.now());\n    this.log.action(serializedName(serialized, \"llm_start\"), spanIds(runId, parentRunId));\n  }\n\n  handleLLMEnd(_output: LLMResult, runId: string, parentRunId: string | undefined): void {\n    this.log.observation(\"llm_end\", { ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });\n  }\n\n  handleLLMError(err: unknown, runId: string, parentRunId: string | undefined): void {\n    this.takeDurationMs(runId);\n    this.log.error(\"llm_error\", { error: formatError(err), ...spanIds(runId, parentRunId) });\n  }\n\n  // -- agent-level events --------------------------------------------------\n\n  handleAgentAction(action: AgentAction, runId: string): void {\n    this.log.action(action.tool || \"agent_action\", { parentSpanId: runId });\n  }\n\n  handleAgentEnd(_action: AgentFinish, runId: string): void {\n    this.log.decision(\"agent_finish\", { parentSpanId: runId });\n  }\n\n  // -- tools: action (start) / observation (end) / error -------------------\n\n  handleToolStart(\n    serialized: Serialized,\n    _input: string,\n    runId: string,\n    parentRunId?: string,\n  ): void {\n    this.callStarts.set(runId, performance.now());\n    this.log.action(serializedName(serialized, \"tool\"), spanIds(runId, parentRunId));\n  }\n\n  handleToolEnd(_output: unknown, runId: string, parentRunId: string | undefined): void {\n    this.log.observation(\"tool_end\", { ...spanIds(runId, parentRunId), durationMs: this.takeDurationMs(runId) });\n  }\n\n  handleToolError(err: unknown, runId: string, parentRunId: string | undefined): void {\n    this.takeDurationMs(runId);\n    this.log.error(\"tool_error\", { error: formatError(err), ...spanIds(runId, parentRunId) });\n  }\n}\n","import { LangChainAdapter } from \"./langchain-adapter.js\";\n\n/**\n * `LangChainAdapter`, for use with LangGraph.js graphs — exported under its\n * own name for discoverability and parity with `logquill-python`'s\n * `LangGraphAdapter`. LangGraph.js nodes run as ordinary LangChain.js\n * `Runnable`s, so `LangChainAdapter`'s `handleChainStart`/`handleLLMStart`/\n * `handleToolStart`/etc. already fire exactly as they would for a plain\n * chain — no extra mapping needed.\n *\n * Unlike `logquill-python`, this class adds no extra event handling.\n * Python's `LangGraphAdapter` exists specifically to catch LangGraph\n * Python's own checkpoint pause/resume events (`on_interrupt`/`on_resume`),\n * which that ecosystem dispatches only to handlers implementing its own\n * `GraphCallbackHandler` — a plain `BaseCallbackHandler` subclass never\n * receives them there. LangGraph.js has no equivalent: as of `@langchain/\n * langgraph` 1.x it exposes no distinct callback-handler class or\n * `onInterrupt`/`onResume` hook — an `interrupt()` call instead pauses the\n * graph and surfaces in its state/stream output (under `__interrupt__`),\n * not through the callback-handler system at all. There is nothing this\n * class could subscribe to that `LangChainAdapter` doesn't already cover.\n *\n * ```ts\n * import { Logger, RunPlugin } from \"logquill\";\n * import { LangGraphAdapter } from \"logquill/langchain\";\n *\n * const handler = new LangGraphAdapter(log.child(\"agent\").use(new RunPlugin()));\n * const graph = builder.compile({ checkpointer });\n * await graph.invoke(input, { callbacks: [handler], configurable: { thread_id: \"1\" } });\n * ```\n */\nexport class LangGraphAdapter extends LangChainAdapter {}\n"]}