@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/coreThe 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 callfailed).
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
unbuilthole (isCompleteis false), a warning is raised, andevidence.recordingStatus()lists it underrefusedbeside 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:
- LangChain's own
artifactfield on a tool message (response_format: "content_and_artifact"), the first-class channel and what a real agent hits. - Raw bytes returned from a tool.
- 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 integrationThe 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 recordmetadata.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 somethingobserved 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, andclosing.promisedon 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:
- 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.
- One name in every SDK.
run.seqmeans the same thing in this package,@sanning/anchor-vercel,@sanning/anchor-interchange, andsanning-anchorfor Python. The shape is shared; only the values are framework-native. - Collection reads these names. The
standardcollection 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 droppedclose() 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.zipReplace 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
eventBytesare the only copy of what the hash commits to, and an envelope without its record proves a commitment existed, not what it said. ConfigurelogStoreon the anchorer and the SDK retains for you, to thelog-store.mdlayout, before the event is anchored. DrainingeventBytesby 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.
