npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@sanning/anchor-langchain

v0.21.2

Published

Anchor your LangChain.js agent's run tree as it executes: one callback handler turns every chain, LLM and tool step into a signed evidence envelope, sent to Sanning and witnessed on an interval to a permanent public record. Prompts and outputs are hashed

Readme

@sanning/anchor-langchain

Anchor your LangChain.js or LangGraph agent's run tree as it executes. Add one callback handler and every chain, chat-model, LLM, tool and retriever step becomes a tamper-evident agent.* record of the sanning.agent/1 vocabulary, along with every file a tool produces. A LangGraph interrupt reads as interrupted, and a tool you name can state a decision.

npm install @sanning/anchor-langchain @sanning/anchor @langchain/core

The concept and the ten-minute quickstart are at docs.sanning.io; the wire format is a spec in sanning-io/proof.

Trace an agent run

import { createAnchorer, FsLogStore, LocalEd25519Signer } from "@sanning/anchor";
import { anchorCallbacks } from "@sanning/anchor-langchain";
import { awaitAllCallbacks } from "@langchain/core/callbacks/promises";

const anchorer = createAnchorer({
  // Writes to a permanent public record. Use "dev" until you mean it.
  environment: "production",
  signer: LocalEd25519Signer.fromSeedHex(process.env.SANNING_SIGNING_SEED!),
  subject: { type: "agent", agent_id: "claims-triage" },
  // The key needs `agent:enroll` and `anchor:write`, and `anchor:read` too
  // if it will later build an evidence pack.
  apiKey: process.env.SANNING_API_KEY!,
  logStore: new FsLogStore("./logstore"),
});

const evidence = anchorCallbacks(anchorer);

let steps, gaps;
try {
  // One line of integration: pass it like any LangChain callback.
  await agent.invoke({ input: question }, { callbacks: [evidence] });
} finally {
  // In `finally`, so a throw from `invoke` still settles every step and
  // closes the run -- without it, an agent that throws leaves no closing
  // record, and a reader cannot tell that apart from a process that died
  // before `close()` ran.
  await awaitAllCallbacks();
  ({ steps, gaps } = await evidence.close());
}

// The handler never closes the anchorer you handed it. Close it once the
// process is done with it, after every handler that uses it.
await anchorer.close({ raiseOnGaps: false });

One anchorer, one handler per request. A handler answers for its own records: gaps, isComplete, assertComplete() and close() count only the records that handler wrote, so one request's lost record never makes another request's trail incomplete. That is why close() leaves the anchorer open: another request may still be using it. anchorer.close() is where a buffered record still pending is reported.

Wait for LangChain's callbacks before close(). LangChain JS can dispatch callbacks in the background, so invoke can return before this handler has seen the root's chain_end, most often beside a slower callback handler. Call await awaitAllCallbacks() (from @langchain/core/callbacks/promises) before close(), or set LANGCHAIN_CALLBACKS_BACKGROUND=false before you construct any callback handler: @langchain/core 1.2.11 reads the variable into a class field at construction, so setting it later has no effect on a handler already built. If you skip it, an end that arrives after close() is refused: it is not anchored, it lands on unbuilt, and assertComplete() throws IncompleteTrailError over it. The closing record was already written without it, so it does not count that end and its observed outcome reads unknown rather than completed.

Prompts, outputs and tool input and output are hashed in this process. The signed envelope carries only the hash, so the bytes never reach Sanning. What each step committed stays with you, in the logStore if you configured one, or in step.result.eventBytes if you drain it yourself.

Enrollment is automatic before the first anchor, so there is no registration step to write. Production refuses auto-generated secrets: createAnchorer throws unless you pass a signer and a subject. Dev proofs are permanently marked environment: "dev" inside the signed bytes, so a dev proof can never be presented as production evidence.

The run tree is the record

LangChain's callbacks carry runId and parentRunId for every step. The handler commits that linkage, plus its own per-invocation chain, inside every record's metadata:

"run": {
  "run_id": "…",
  "parent_run_id": "…",
  "root_run_id": "…",
  "seq": 3,
  "prev_event_id": "…"
}

Each record points at its predecessor, and every pointer lives inside individually signed bytes. Drop a record and the next one's pointer dangles; reorder them and seq disagrees; edit one and its hash breaks. The result is a deletion-evident, reorder-evident tree of everything the agent did, reconstructable offline from the records alone.

Chaining is on by default, and that default is the point: an unchained set cannot distinguish "nothing else happened" from "something was removed". Pass chain: false to opt out, or a function to choose the chain key.

The key function receives the record as placed: its type, the content it commits to, and where it sits. chain: (e) => (e.content as { tenant_id: string }).tenant_id keys a chain per tenant. sanning-anchor on PyPI hands its key function the same fields under Python's names, as an AnchorEvent, so an agent ported between the two SDKs produces the same chain topology.

What the handler writes

Every record is built by buildAgentRecord, which checks it against the sanning.agent/1 schema before it is signed. An invocation is one root run:

| Record | When | |---|---| | agent.run_opened | The first record of the invocation. It commits the input, announces that a closing record is coming (closing.promised), and lists in capture.not_captured the record types this adapter cannot write. | | agent.step.started, agent.step.ended | A chain, a graph node or the root. The root's end is the invocation's output. LangGraph's own steps carry run.plumbing, read from the tag LangGraph sets, never from a name. | | agent.model_call.started, .ended | A chat model or LLM call. | | agent.tool_call.started, .ended | A tool call. gen_ai.tool.call.id is on both: the model's id, or an id this adapter assigns from the run id when the framework gave none. | | agent.retrieval.started, .ended | A retriever call. | | agent.step.occurred | A moment LangChain reports as one event: an agent action (run.source_type langchain.agent_action) and an agent finish (langchain.agent_finish), inside the run LangChain names. One record, with no start, no end and no outcome. LangChain JS reports no retry to a callback handler, so this adapter writes none; the Python adapter does. | | agent.file | A file a tool produced, one record per file. | | agent.decision | A named tool ended completed (below). | | agent.approval.requested, .resolved | A LangGraph interrupt and its answer (below). | | agent.run_closed | Written by close(), once per root run. |

A start and its end carry the same run.run_id, and the end names its start in run.started_event_id. A step that occurred commits the event as LangChain handed it: the AgentAction or the AgentFinish. A customer's own event from dispatchCustomEvent is not recorded.

Each record commits the object the framework handed the callback: a chain's inputs or outputs, a model call's messages or prompts, a tool's input or output, a retriever's query or documents, or an error as { "message", "type" }. The adapter does not author a summary of it.

What this adapter cannot capture

capture.not_captured on the first record is the adapter's own word on what it does not write. Here it names agent.handoff.sent and agent.handoff.received always, agent.decision unless you name decision tools, and both approval types unless you configure approvals. An absent list says the adapter declared nothing, never that it captures everything.

A LangGraph pause and resume

When a node calls interrupt(), LangGraph ends the run and reports the root as completed. The handler reads it as it is: the node's agent.step.ended and the root's carry outcome.status: "interrupted", and the closing record observes interrupted.

interrupt() does not say who decides, and a resume value is any JSON, so the approval records need two things from you:

const evidence = anchorCallbacks(anchorer, {
  approvals: {
    actor: "human",
    // Read the resume value as an answer; throw for a value that is no verdict.
    verdict: (resume) => (resume === "yes" ? "approved" : "rejected"),
  },
});

The handler then writes agent.approval.requested before the interrupted node ends, and keeps that record's event_id with the conversation (LangGraph's thread_id). The invocation that resumes the thread writes agent.approval.resolved, naming the request in run.started_event_id. The two records are in different runs and are tied by gen_ai.conversation.id. The conversation id is the thread_id as LangGraph gave it, never generated. A thread_id is an id: 1 to 128 characters of A-Z a-z 0-9 _ . : -. One outside that grammar, such as an email address, is never rewritten or left out, so every record of the run is refused and reported as unbuilt, and the agent still runs. Use an opaque thread_id.

When interrupt() is called inside a tool, the tool call ends interrupted in the invocation that started it, not failed. On resume LangGraph runs the tool again as a new tool call, with its own start and end, and the answer writes no end for the old one.

The approval's subject, approval.subject_event_id, is the agent.step.started of the node that paused for the answer, not the start of a tool call. A verifier warns ran_after_refusal when a tool call ran after its approval refused it, and that check does not cover these runs: the re-run after a resume is a new operation that nothing links to the refusal. The records still show both.

What Sanning can see after an answer depends on how you built the agent. In private it does not receive the verdict, so it can only look at what follows the answer (section 7 of the vocabulary):

  • When an approval node routes on the answer, an approved run shows a tool call and a decision (where you name a decision tool) after the answer, and a rejected run shows neither.
  • When interrupt() is called inside the tool, the tool runs again on both answers, so the records look the same whichever way the answer went (unless the tool raises on a rejection, which ends the call failed).

Pending approvals are kept in this process by default. If the resume can arrive in another process, pass approvals.pending, an ApprovalStore from @sanning/anchor: put(conversationId, pending), list(conversationId), take(conversationId, requestedEventId) and clear(conversationId), each returning a value or a promise of one, and each bounded by APPROVAL_STORE_TIMEOUT_MS (30 seconds). The store's contract, which includes that take is atomic, and an example on Redis are in the "Record an agent run" section of the @sanning/anchor README. The store holds one entry per interrupt. An interrupt inside a subgraph or a nested runnable reaches the handler at each chain level it passes through, so the handler writes an agent.approval.requested per level, and each one replaces the last in the store: the outermost is the one a resume answers. A resume answers the one request pending on the thread. With two or more pending (two interrupts), it cannot tell which one the resume answers, so the answer is an unbuilt hole and the requests stay pending; a single request whose decider is not approvals.actor is an unbuilt hole too. Input on the thread that is not a Command({ resume }) makes LangGraph discard the interrupted task, so the handler removes the thread's pending requests with clear and warns, naming each one; they stay unanswered in the trail. This holds when the thread id first appears on a child run too, and a resume never removes anything. After close(), a callback writes nothing: a resume then is an unbuilt agent.approval.resolved. A resume with no pending approval, or whose store read runs past the limit, writes no answer and names both approval types as not captured.

Only a LangGraph Command({ resume }) answers a pending approval; ordinary input with a resume key does not. A verdict or reviewer that throws costs the resolution: it is an unbuilt hole (isComplete is false), and the run's other records are written. A resume takes the request it answers out of the store whether or not its answer is written: after close(), when the answer cannot be built, and when verdict or reviewer throws. A missing answer is a hole the trail shows, where a request left behind would let a later resume write an answer nobody gave. It takes a request only when exactly one waits on the thread and approvals.actor decides it. A store that throws costs the resolution too, and a request it could not remove stays for a later resume to answer.

Run one resume per thread at a time. Two processes that resume one thread at once can both read the request before either takes it, and each writes an answer to it.

A slow store slows the agent. A resume reads the store before its first record, so a list that does not answer holds that record, and every call queued behind it, for up to 30 seconds. The handler does not wait for a put or a take before the next record, and close() waits for the store calls still running.

One invocation must run in one process. The handler keeps the root run's position in memory, so running one invocation across several workers is not supported. A resume is a new invocation and can run in any process that reaches the store.

Decisions from a named tool

State each decision in a tool call, and name the tool and the decision:

const evidence = anchorCallbacks(anchorer, {
  decisions: [{ tool: recordConclusion, name: "credit_verdict" }],
});

When record_conclusion ends completed, the handler writes agent.decision named credit_verdict, whose value is what the tool returned (hashed with the record, shown only if revealed). Pass the tool object: a tool that does not exist, a tool named twice, or a name that is no label is refused when the handler is constructed.

The tool is matched by name: a tool with the same name triggers it. A call that ends failed, including a ToolMessage with status error, writes no decision. A tool run whose name the handler cannot read (a class-based tool invoked directly, with no tool call) is reported as a lost agent.decision on unbuilt, never dropped.

Name the decision for what was decided, and put the outcome in the value. credit_verdict with the value declined is right; credit_declined is not, because the name then carries one outcome and a reader cannot compare decisions.

An id that fails the grammar

An id is 1 to 128 characters of A-Z a-z 0-9 _ . : - (a tool call id, 1 to 256). The handler checks each id it writes (the run ids, the thread_id, the tool call id) and refuses a record whose id fails, naming the field and never the value. LangChain swallows a callback's error unless raiseError is set, so:

  • With an anchorer built with failClosed: true, the callback throws and the agent stops before its work.
  • By default the agent keeps running. The record is an unbuilt hole (isComplete is false), a warning is raised, and evidence.recordingStatus() lists it under refused beside the anchorer's own status.

Record the files a tool produces

No setup. A tool that writes a file gets a record per file, committed to the file's own bytes, with nothing passed and no resolver written. Anchoring the tool call proves the agent asked for a file; it does not prove which file came back, and "is this the report that was filed?" is the question an auditor asks second.

Three shapes are recognised in a tool's return value:

  1. LangChain's own artifact field on a tool message (response_format: "content_and_artifact"), the first-class channel and what a real agent hits.
  2. Raw bytes returned from a tool.
  3. A path, the whole return value, which is what a tool that saves a file returns.
const exportReport = tool(async ({ label }) => String(await saveCsv(label)), {
  name: "export_report",
  description: "Write the decision report and return where it was saved.",
  schema: z.object({ label: z.string() }),
});
// that is the entire integration

The record commits to the file itself. Its event.content_hash is the SHA-256 of the file, and the bytes go to your log store as the record's content, exactly like any other content, so bundle discloses or withholds them as usual. They are never sent to Sanning. metadata.artifact names the file (name, size, and path, media type and role where known), links it to the tool call that returned it (tool_call_event_id) and carries no hash: nothing matches a file by its metadata. An auditor holding the file runs sha256sum, or proof verify --files, and compares the result to event.content_hash, with no Sanning write code in that step.

The committed content is the file's own bytes, not a descriptor {name, byte_length, sha256}: a descriptor would commit to something no real file handed in beside a pack could match.

A file the SDK cannot read becomes its own record, an agent.file with outcome.status: "failed" and artifact.reason (not_found, outside_root, not_a_regular_file, too_large, read_failed or path_reading_disabled), rather than a warning nobody sees. Silence is how three files went unrecorded on a run that reported success.

Reading is scoped to a folder, and the folder limits reading rather than storing anything. It defaults to process.cwd(), because a tool result is model-influenced text and following a path out of one is an untrusted read:

anchorCallbacks(anchorer, {
  artifacts: {
    root: "/srv/agent/workspace", // narrow it, widen it, or null to read no paths
    maxBytes: 50 * 1024 * 1024,   // default 25 MiB (DEFAULT_ARTIFACT_MAX_BYTES); above this a file is recorded unreadable, never truncated
  },
});

A file is recorded only when the tool result says it came back: never scraped from prose, never discovered by watching a folder, never from a constant or a configured list. A bare string is treated as a path only if a file exists there, so an ordinary tool returning ordinary text records nothing and says nothing.

The file role. A tool that returns an object shape -- { bytes, name }, { path } -- can name role, source and/or destination alongside it, and every one lands on the record unchanged:

return { path: outPath, name: "decision.pdf", role: "output", destination: "s3://reports/" };

All three are optional and independent, and absent unless the tool names them: a bare string or raw bytes with no role attached carries none of the three. source/destination are the tool's own words, carried verbatim -- this SDK never parses or validates them, and they sit at the same disclosure tier path already does.

The closing record

Written once per root run, automatically, when close() runs. It lists how many records that root run produced and which:

const { steps } = await provenance.close();
const closing = steps.find((s) => s.event.eventType === "agent.run_closed");
closing.event.eventId; // this root run's own closing record

metadata.closing.record_count and record_ids are built from what was actually anchored, meaning the anchorer accepted the record, never from what was attempted, so a record that failed to anchor never inflates the count. With a buffering anchorer a record is durable in your recording buffer and may not have reached Sanning yet; anchorer.recordingStatus() answers that, not this count. A root run that anchored nothing still gets a closing record stating record_count: 0.

Telling "not finished yet" apart from "no such feature". The run's first record, agent.run_opened, carries metadata.closing.promised: true. Read beside the closing record: promised and a later agent.run_closed means the run closed cleanly; promised and no agent.run_closed means the process ended (crashed, was killed, never called close()) before it finished.

How the run ended, and why

closing.outcome.observed.status; // "completed" | "failed" | "interrupted" | "unknown"
closing.outcome.observed.reason; // "error" or "interrupted", when it did not complete
closing.outcome.stated;          // what YOU said at close(), when you said something

observed is what this adapter watched LangChain do, read from the root run's own terminal callback:

| Status | What it means | |---|---| | completed | The root run's terminal callback reported success. | | failed | It reported an error (reason error). The error's words are in the content of the .ended record that carries it. | | interrupted | A LangGraph node interrupted the run (reason interrupted). Never completed. | | unknown | The adapter never saw this run end, or the record of its end did not anchor. |

unknown is a fact, not a shrug. An adapter that guessed completed because nothing looked broken would put a claim it cannot stand behind inside permanent, signed evidence. A child run's failure that the agent recovered from does not make the turn failed, and a failed is never overwritten by a later clean end.

An operation that has no end when close() runs gets no end written for it, and a warning names it. When the root's own end is among the records the closing record lists, such a run reads interrupted, with no reason, in place of completed; a failed stays failed, and a run whose root end is not among them reads unknown.

Putting the records in a case: caseId

bundle --case <id> selects on each record's own signed context.case_id, and this adapter writes none unless you name the case:

const evidence = anchorCallbacks(anchorer, { caseId: "case-4b19de" });

Every record then carries it. caseId follows the grammar anchor({ caseId }) applies (128 characters or fewer, ^[A-Za-z0-9_.:-]+$) and is refused at construction. It is committed permanently, so keep it opaque. In Python the option is AnchorCallbackHandler(anchorer, case_id=...).

Closing a case, not a turn

A root run is one turn. A case is often several turns across several services, and nothing in LangChain knows that. You know the case, so you name it:

const evidence = anchorCallbacks(anchorer, { caseId });
try {
  await agent.invoke(input, { callbacks: [evidence] });
  await handOff(result);              // the checker refuses it
  await evidence.close({ outcome: "completed" });
} catch (err) {
  await evidence.close({ outcome: "failed", reason: "error" });
  throw err;
}

close({ outcome, reason }) lands as closing.outcome.stated, beside what the adapter observed and never over it. outcome is completed, failed, interrupted or unknown; reason is a code: error, timeout, cancelled, interrupted or policy. Free text, a reason with no outcome and a status outside the list are refused before anything is anchored.

A close() that states an outcome after an earlier close() reports loudly and does not rewrite the closing records, which the first call writes once: state it on the first close(). The second of two concurrent close() calls waits for the first one's closing records for at most 120 s, then throws ClosingNotDeliveredError (from @sanning/anchor).

What the SDK does NOT say

  • The run held no signing key, so it anchored nothing. There is no closing record, and a status inside a record cannot describe that record's own absence.
  • The closing record itself failed to anchor. close() reports it as a chain gap or an unbuilt record, and closing.promised on the first record is what tells a reader a closing record was promised and never arrived.

The promoted fields

Every callback commits the whole step in the record body. On top of that, a closed list is copied into named metadata. Three reasons, and each field earns its place against all three:

  1. Findable without reading the body. The body is yours, it can be large, and when you build the evidence pack it may be withheld. A promoted field is legible from the record alone.
  2. One name in every SDK. run.seq means the same thing in this package, @sanning/anchor-vercel, @sanning/anchor-interchange, and sanning-anchor for Python. The shape is shared; only the values are framework-native.
  3. Collection reads these names. The standard collection level collects this list, so the fact is defined once rather than re-derived per integration.

Show which policy a step applied. Have the tool that reads or applies the policy return the file as its artifact. The adapter then writes a agent.file record that commits to the file's bytes, on that tool's run, so the trail shows which policy a step actually read rather than which one was configured at startup:

const readPolicy = tool(
  async () => ["Loaded underwriting policy v3.", { path: "./policies/underwriting-v3.md" }],
  {
    name: "read_underwriting_policy",
    description: "Read the underwriting policy in force.",
    schema: z.object({}),
    responseFormat: "content_and_artifact",
  },
);

An auditor holding the policy runs sha256sum and compares the result with that record's event.content_hash. The file's bytes go to your log store as the record's content, never to Sanning. Hashing documents named at startup would record a declaration, not what any step read, so there is no option for it.

| Field | Why it is promoted | |---|---| | run.run_id | Names the step itself, so its start, end and error events join without inferring anything from emission order. | | run.parent_run_id | Its parent, so the tree is reconstructable from the records alone. | | run.root_run_id | The invocation the whole set belongs to, which is how you select one run out of a store holding many. | | run.seq | Its ordinal within that root. A hole in seq is a missing event, visible offline with no cooperation from Sanning. | | run.prev_event_id | The previous event's id. Delete an event and the next one's pointer dangles; reorder and the chain disagrees. | | run.name | The step's name, as LangChain names the run: the run name it passed, else the serialized object's name, else its class (LangChain's own rule). A trail reads as steps (write_assessment, read_credit_policy) without opening a record. On every record of the run. Off with recordNames: false. | | run.client | The LangChain client class a model call went through (ChatOpenAI). model.provider does not carry it. On every record of a model run. | | artifact.name, artifact.byte_length | The file a tool produced, on an agent.file record only. artifact.path, artifact.content_type and artifact.tool_call_event_id join them where known. No hash: the file's SHA-256 is the record's event.content_hash, which is what an auditor's sha256sum has to match. | | artifact.role, artifact.source, artifact.destination | The file role: input or output, and where it came from or went, all customer-supplied and all absent unless the tool named them. | | otel.trace_id, otel.span_id | The ids of the real OpenTelemetry span this step ran inside, so an evidence record joins the tracing you already have. Read from the OTel API your process registered; this package takes no telemetry dependency. | | otel.scope.name, otel.scope.version, otel.scope.schema_url | The recorder that wrote the record: @sanning/anchor-langchain and its published version, and https://opentelemetry.io/schemas/1.41.0, the version of the OTel names below. On every record. | | gen_ai.request.model | The model as you named it (was model.id). Its absence is what prompted this list: a record of an LLM call that does not say which model is evidence of very little. | | gen_ai.request.temperature, .max_tokens, .seed, .top_p | The settings the call was made with, from the client's invocation parameters, in OTel's types. The same model answers differently under different settings. | | gen_ai.provider.name | The service that served the call: openai, anthropic, groq and OTel's other well-known values, plus openrouter. In TypeScript, signed only from an endpoint visible in the client's own config; env and defaults give no provider; absent otherwise, and never a class name. See below for how it is decided. | | gen_ai.prompt.name | The name you gave the prompt for this call, from the run's metadata (below). | | gen_ai.response.model | The model the provider says answered (was model.id_returned). A different fact from what was asked for, which is why there are two fields and not one. | | gen_ai.response.id | The provider's own id for the response (chatcmpl-…, msg_…, gen-…): the one fact that follows a call into the provider's log. | | gen_ai.response.finish_reasons | Why the model stopped, one entry per generation, in the provider's own words (stop, tool_calls, end_turn). Always an array. | | gen_ai.usage.input_tokens, .output_tokens, .reasoning.output_tokens | What the response cost, as the provider counted it. | | openai.response.system_fingerprint | The provider's marker for its serving configuration, where an OpenAI-compatible response carries one. OpenAI's own namespace, so not under gen_ai. | | gen_ai.tool.name | The tool's own name, on its start, result and error records: the name the model's tool call gave that call id, since LangChain.js shows a tool's name nowhere else. Never the run name, which a caller's runName replaces. Absent for a tool run with no tool call id. Off with recordNames: false. | | gen_ai.tool.call.id | The model-emitted id of the tool call, or the id this adapter assigned from the run id when the framework gave none. On both the start and the end record. | | gen_ai.agent.version | Your version for your agent, from the agentVersion option, on every record. Your claim about your own code. | | closing.record_count, closing.record_ids | The closing record: how many records this root run anchored (the anchorer accepted them) and their ids (recordingStatus() says what reached Sanning), on the one agent.run_closed record per root run, written at close(). record_count is always record_ids.length. | | closing.outcome.observed | How the run ended as this adapter watched it end: { status, reason? }, status one of completed, failed, interrupted, unknown. Present on every closing record; unknown when the adapter never saw the run end. | | closing.outcome.stated | How you said it ended, from close({ outcome, reason }). Absent unless you said something. Never replaces observed: a disagreement between the two is a fact a reader must see. | | closing.promised | The announcement that a closing record is coming, on the invocation's first record, agent.run_opened. Always true when present; absent, never false. |

Absent, never empty. A field we do not know does not appear: no "", no "unknown". The exceptions are run.parent_run_id and run.prev_event_id, which carry an explicit null. null there is a fact (this step is a root; this is the chain's first event), and a reader must not have to guess which of "absent" and "no parent" they are looking at. otel.trace_id and otel.span_id appear only when a real span exists: a LangChain run id is a UUID the framework invented and an OTel span id is 16 bytes from an actual span, so promoting one as the other would assert an identity we never obtained.

The gen_ai names are OpenTelemetry's. They follow the OTel GenAI semantic conventions, pinned to v1.41.0, nested so the JSON path reads as the attribute name: metadata.gen_ai.request.model is gen_ai.request.model. v1.41.0 is the last core release where these names are current. From v1.42.0 the core repository marks them moved to open-telemetry/semantic-conventions-genai, which has no release yet; the names themselves did not change. Sanning moves the pin deliberately once that repository releases, never by following core.

How gen_ai.provider.name is decided. It is a signed claim about which service served the call, so in TypeScript it is written only from an endpoint visible in the client's own config: environment variables and defaults give no provider in TypeScript. The base URL must be in the client's serialized kwargs, which LangChain.js writes in snake_case: configuration.baseURL or base_url for ChatOpenAI, anthropic_api_url or client_options.baseURL for ChatAnthropic, base_url for ChatGroq and ChatGoogleGenerativeAI, server_url for ChatMistralAI, configuration.baseURL for ChatDeepSeek.

The provider is that endpoint's host: ChatOpenAI pointed at openrouter.ai is openrouter. In every other case the field is absent: no visible endpoint (a client left at its default, an endpoint set through OPENAI_API_BASE, ANTHROPIC_API_URL or LANGSMITH_GATEWAY, or built with createClient), a client class not listed above (including ChatXAI, which does not serialize its baseURL), a client that serializes as not_implemented, a host this package does not know (a local server, a proxy, the LangSmith gateway). run.client still records the class.

The adapter does not read the environment or assume a default because the clients disagree: @langchain/openai before 1.5.6 and @langchain/anthropic before 1.5.4 ignore the variables newer releases read, and createClient can replace the client with one that calls another service (Bedrock, Vertex). A provider you want recorded, set it with the client's base-URL option so it is in the config. The table is pinned by captures from the published clients in tools/langchain-callback-conformance/provider-captures.json.

Name a prompt by putting its name in the run's metadata under the OTel attribute's own name. LangChain passes a run's metadata down to the model calls inside it:

await agent.invoke(input, {
  callbacks: [handler],
  metadata: { "gen_ai.prompt.name": "underwrite-v3" },
});

What this adapter cannot fill. Every field above is filled where LangChain hands it over and absent where it does not. In practice: gen_ai.response.id is absent when the provider integration puts no id on the message (LangChain then mints its own run-… id, which is never written as the provider's); gen_ai.usage.* is absent when neither usage_metadata nor llmOutput carries counts; openai.response.system_fingerprint is absent for non-OpenAI-compatible providers and when the server sends an empty one; gen_ai.tool.name uses the run name LangChain.js hands a tool, which is the tool's name unless you override runName on the tool call.

Names, and keeping them out. run.name and gen_ai.tool.name are signed by default. A record's metadata is visible whenever the record is, even in a pack whose content is withheld, and a tool's name can say more than you meant (lookup_customer_ssn). recordNames: false omits both, and only those two:

anchorCallbacks(anchorer, { recordNames: false, agentVersion: "2026.10.1" });

The names then stay only in the committed content, hashed and withheld like the rest of it.

The list is closed. Adding to it takes a change with a one-line justification per field, and nothing joins it quietly. A field the model reported that is not on the list is still in the body: nothing is dropped, it is only not promoted.

Note: these are names a customer authored, and a model name can encode a project, so they are in scope for your own leak review. They record what the integration reported, never proof of what actually served the request.

What gets committed, and what you can do about it

The object the framework handed the callback. Each record commits that object as the framework gave it, never summarised. Only the hash reaches Sanning; the bytes go to your own store.

onEvent lets you watch what is committed. It cannot change it:

const evidence = anchorCallbacks(anchorer, {
  onEvent: (e) => metrics.count(e.eventType),   // observe; cannot alter
});

A hook that could trim or drop a record before it is hashed would leave a chain with no sign that a step had been withheld, so there is none.

Withholding belongs when you build the evidence pack instead. The evidence set stays complete, and the pack's disclosure decides what actually travels to a third party, a choice you make per recipient over a record that can still prove nothing was lost. Credential-shaped values are scrubbed automatically: the whole value of a key that looks like api_key, authorization or password becomes "[scrubbed]" before hashing, and the record says so in context.content_scrubbed.

When a step cannot be anchored

The trail never claims completeness it does not have. An event that cannot be anchored still burns its chain slot, so the survivors cannot close ranks over it: the next record of the run, if one is delivered, skips its seq and names it as its predecessor, which an auditor sees offline, with no cooperation from Sanning. Where nothing follows it (the closing record is always last), nothing dangles: the closing announcement is what makes a missing closing record readable, and close() reports every hole either way.

const { steps, gaps } = await evidence.close();
evidence.isComplete; // false if anything was dropped

close() settles every step and returns both, and it does not throw by default; pass { raiseOnGaps: true } to make an incomplete trail an error. A gap is reported undelivered, never as a bad record: a timeout says nothing about whether the plane accepted it. Its eventBytes are retained, and after a failure they are the only copy of something that may already be committed.

Provenance never crashes the agent: content that fails to serialize (a lone UTF-16 surrogate, a cycle) is reported through warn and recorded as an unbuilt gap, and the run continues. So is a step whose callback threw before its record was attempted: it is on unbuilt, not missing.

The one exception is an anchorer built with failClosed: true. The handler then waits for each step's records (it sets LangChain's awaitHandlers and raiseError), and when it loses a record it throws out of the callback, so the step does not go ahead: a tool whose agent.tool_call.started record is lost does not run. A lost record is any record of this handler's that is not in the trail: one the plane refused, one the handler could not build (the chain key function threw, the content would not serialize or an id failed the grammar), one a chain-store failure cost, a step whose callback threw before its record, and the record of a file a tool returned, which is written after the tool's tool_end and which every later step waits for. The handler then stays stopped: every later step writes its own record and throws the same error, and a new run on it throws an error that says to construct a new handler. Under a real createAgent, LangGraph's tool node turns a throw from the tool's callback into an error message for the model, so invoke rejects from the next step, with the same error, or with RecordingHaltedError when the anchorer halted. Every step waits for its record, which is the cost. A throw after a step's record was attempted (a bug in the handler) does not stop the agent. An error callback never throws (the run is already stopping), but a record it loses still stops every later step. With a buffer, a record is lost only once a later drain is refused for good, so the agent stops at the step after it. See docs/buffering.md.

Hand over a pack

Evidence leaves as one zip, assembled months later from the Sanning index and your own log store, with no signing key involved:

export SANNING_API_KEY=ANCHOR_READ_KEY   # the key needs the `anchor:read` scope

npx @sanning/anchor bundle \
  --agent claims-triage \
  --from 2026-06-01 --to 2026-06-30 \
  --logs ./logstore \
  --out claims-triage-2026-06.zip

Replace ANCHOR_READ_KEY with a key from the console carrying anchor:read. --logs takes a local store root or an s3:// URL, and a bucket is read with the standard AWS settings (AWS_*, or the AWS credential chain). The auditor unzips and verifies offline, in two steps, because handing the CLI a .zip fails with a JSON parse error and handing it a directory fails with EISDIR:

unzip pack.zip -d pack
cd pack
npx @sanning/proof verify bundle.json --logs logs/

Replace pack.zip with the name the pack arrived under. It prints a per-event and rollup verdict, verified, failed or incomplete, read from what the pack holds, and exits on the kernel's one table: 0 verified, 1 failed, 2 incomplete, 3 verified with sandbox records, 4 could not run. A pack states no verdict of its own. A record whose bytes are withheld leaves the pack incomplete, never failed.

Full flags and the Python equivalent: @sanning/anchor.

Semantics

  • Retention is one option, not a loop you write. External commitment means eventBytes are the only copy of what the hash commits to, and an envelope without its record proves a commitment existed, not what it said. Configure logStore on the anchorer and the SDK retains for you, to the log-store.md layout, before the event is anchored. Draining eventBytes by hand stays supported for callers who want it.
  • Lifecycle is explicit. await evidence.close() settles every step and writes the closing records; await anchorer.close() closes the anchorer. There are no hidden process-exit hooks.
  • Provenance, not endorsement: a verified history says what happened, never "safe" or "approved".

License

MIT. The framework is a peer dependency; this package depends only on @sanning/anchor.