Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions docs/host-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,16 @@ family traits. For an unregistered generic model, forced reserved names (`auto`,
`none`, `any`, `required`) fail closed instead of being interpreted as a different
choice. An empty selection explicitly
binds an empty tool list when the descriptor contains tools. Native messages are
snapshotted through LangChain's stored-message representation before asynchronous
provider dispatch. Host-local V8 serialization preserves binary data, dates,
snapshotted through the SDK's `toStoredMessage` representation before asynchronous
provider dispatch. The same helper is exported for transport/checkpoint adapters:
it reads current native message fields without LangChain's JSON-oriented escaping,
so binary data, dates, maps, sets, tool artifacts and caller tag fields reach the
adapter's codec intact. It returns field references, not a deep copy or a wire
encoding; the adapter must apply its own bounded snapshot/encoding immediately.
Custom messages declaring `lc_secrets` fail closed and require an explicit codec;
this helper does not silently bypass their secret-redaction contract.
A chunk-aware codec must preserve chunk kind separately, because the standard
LangChain stored-message decoder constructs full messages. Host-local V8 serialization preserves binary data, dates,
BigInts, maps and sets instead of coercing them through JSON. Functions and other
uncloneable values fail closed. The returned descriptor is a separate copy.

Expand Down
41 changes: 3 additions & 38 deletions src/harness/modelService.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,6 @@ import {
import {
isAIMessage,
isAIMessageChunk,
isToolMessage,
isChatMessage,
isBaseMessageChunk,
isBaseMessage,
mapStoredMessagesToChatMessages,
} from '@langchain/core/messages';
Expand Down Expand Up @@ -40,6 +37,7 @@ import {
} from './model';
import { modelStreamCallbacks } from './modelStreamCallbacks';
import { getProviderFamily } from '@/llm/providers';
import { toStoredMessage } from '@/messages/stored';

interface ModelLease {
charge(bytes: number): void;
Expand Down Expand Up @@ -144,47 +142,14 @@ const requestSchema = z.object({
.optional(),
});

/** Preserve current native fields; BaseMessage.toDict() JSON-coerces structured metadata. */
function storedMessage(message: BaseMessage): StoredMessage {
const data = {
...message.lc_kwargs,
content: message.content,
additional_kwargs: message.additional_kwargs,
response_metadata: message.response_metadata,
id: message.id,
name: message.name,
role: isChatMessage(message) ? message.role : undefined,
tool_call_id: undefined,
...(isAIMessage(message)
? {
tool_calls: message.tool_calls,
invalid_tool_calls: message.invalid_tool_calls,
usage_metadata: message.usage_metadata,
}
: {}),
...(isBaseMessageChunk(message) && isAIMessageChunk(message)
? { tool_call_chunks: message.tool_call_chunks }
: {}),
...(isToolMessage(message)
? {
tool_call_id: message.tool_call_id,
artifact: message.artifact,
status: message.status,
}
: {}),
};
// LangChain's StoredMessageData types content as string, but its codec supports native blocks.
return { type: message.getType(), data } as StoredMessage;
}

function messageBytes(
messages: readonly BaseMessage[],
maxBytes: number
): number {
let bytes = 2;
try {
for (const message of messages) {
bytes += serializeNativeValue(storedMessage(message)).byteLength + 1;
bytes += serializeNativeValue(toStoredMessage(message)).byteLength + 1;
if (bytes > maxBytes) throw new HostModelServiceError('overflow');
}
return bytes;
Expand Down Expand Up @@ -355,7 +320,7 @@ export function createHostModelService(options: {
if (bytes > limits.maxRequestBytes)
throw new HostModelServiceError('overflow');
for (const message of value.messages) {
const serialized = serializeNativeValue(storedMessage(message));
const serialized = serializeNativeValue(toStoredMessage(message));
const added = serialized.byteLength + 1;
bytes += added;
if (bytes > limits.maxRequestBytes)
Expand Down
1 change: 1 addition & 0 deletions src/messages/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,4 @@ export * from './assistantPhase';
export * from './provenance';
export * from './projectionInvariant';
export * from './fading';
export { toStoredMessage } from './stored';
121 changes: 121 additions & 0 deletions src/messages/stored.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
import { serialize, deserialize } from 'node:v8';
import {
AIMessage,
AIMessageChunk,
ChatMessage,
HumanMessage,
ToolMessage,
mapStoredMessagesToChatMessages,
} from '@langchain/core/messages';
import type { BaseMessage, StoredMessage } from '@langchain/core/messages';
import { toStoredMessage } from './stored';

function roundTrip(message: BaseMessage): BaseMessage {
const stored = deserialize(
serialize(toStoredMessage(message))
) as StoredMessage;
return mapStoredMessagesToChatMessages([stored])[0];
}

it('retains native values nested inside messages for the caller codec', () => {
const fields = {
bytes: Uint8Array.from([1, 2, 255]),
date: new Date('2026-01-01T00:00:00Z'),
map: new Map([['key', new Set([1, 2])]]),
large: BigInt('12345678901234567890'),
missing: undefined,
reserved: { lc: 1, type: 'constructor', $sdk: 'bytes', value: 'user data' },
};
const message = new HumanMessage({
content: 'hello',
additional_kwargs: fields,
});
expect(roundTrip(message).additional_kwargs).toEqual(fields);
});

it('uses live message fields, including values assigned after construction', () => {
const message = new AIMessage('old');
message.content = [{ type: 'text', text: 'current' }];
message.id = 'current-id';
message.name = 'current-name';
message.response_metadata = { model_name: 'host-model' };
message.additional_kwargs = { current: true };
message.tool_calls = [{ id: 'call', name: 'inspect', args: { id: 1 } }];
message.invalid_tool_calls = [
{ name: 'broken', args: '{', error: 'invalid' },
];
message.usage_metadata = {
input_tokens: 7,
output_tokens: 3,
total_tokens: 10,
};
expect(roundTrip(message)).toMatchObject({
content: message.content,
id: message.id,
name: message.name,
response_metadata: message.response_metadata,
additional_kwargs: message.additional_kwargs,
tool_calls: message.tool_calls,
invalid_tool_calls: message.invalid_tool_calls,
usage_metadata: message.usage_metadata,
});
});

it('preserves tool artifacts, status and the live tool-call identity', () => {
const message = new ToolMessage({
content: 'result',
tool_call_id: 'original',
});
message.tool_call_id = 'current';
message.status = 'error';
message.artifact = {
bytes: Uint8Array.from([3, 4]),
date: new Date('2026-01-01Z'),
};
expect(roundTrip(message)).toMatchObject({
tool_call_id: 'current',
status: 'error',
artifact: message.artifact,
});
});

it('preserves the role of generic chat messages', () => {
const message = new ChatMessage({ role: 'custom', content: 'message' });
expect(roundTrip(message)).toMatchObject({
role: 'custom',
content: 'message',
});
});

it('preserves AI chunk fields for a chunk-aware transport', () => {
const message = new AIMessageChunk({
content: '',
tool_call_chunks: [{ name: 'inspect', id: 'call', args: '{', index: 0 }],
usage_metadata: { input_tokens: 7, output_tokens: 0, total_tokens: 7 },
});
const stored = toStoredMessage(message);
expect(stored.data).toMatchObject({
tool_call_chunks: message.tool_call_chunks,
usage_metadata: message.usage_metadata,
});
});

it('does not silently erase unsupported values before the bounded codec can reject them', () => {
const message = new HumanMessage({
content: 'hello',
additional_kwargs: { closure: () => 'private' },
});
expect(() => serialize(toStoredMessage(message))).toThrow();
});

it('fails closed for custom secret-bearing message serializers', () => {
class SecretMessage extends HumanMessage {
override get lc_secrets() {
return { 'additional_kwargs.token': 'TOKEN' };
}
}
const message = new SecretMessage({
content: 'hello', additional_kwargs: { token: 'PRIVATE' },
});
expect(() => toStoredMessage(message)).toThrow('secrets require an explicit codec');
});
48 changes: 48 additions & 0 deletions src/messages/stored.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
import {
isAIMessage,
isAIMessageChunk,
isToolMessage,
isChatMessage,
isBaseMessageChunk,
} from '@langchain/core/messages';
import type { BaseMessage, StoredMessage } from '@langchain/core/messages';

/**
* Native stored-message data without LangChain's JSON-oriented object escaping.
* Values retain their native types and references: callers must snapshot/encode
* with their own bounded codec before retaining or transmitting the result.
*/
export function toStoredMessage(message: BaseMessage): StoredMessage {
if (Object.keys(message.lc_secrets ?? {}).length > 0) {
throw new Error('SDK native message secrets require an explicit codec');
}
const data = {
...message.lc_kwargs,
content: message.content,
additional_kwargs: message.additional_kwargs,
response_metadata: message.response_metadata,
id: message.id,
name: message.name,
role: isChatMessage(message) ? message.role : undefined,
tool_call_id: undefined,
...(isAIMessage(message)
? {
tool_calls: message.tool_calls,
invalid_tool_calls: message.invalid_tool_calls,
usage_metadata: message.usage_metadata,
}
: {}),
...(isBaseMessageChunk(message) && isAIMessageChunk(message)
? { tool_call_chunks: message.tool_call_chunks }
: {}),
...(isToolMessage(message)
? {
tool_call_id: message.tool_call_id,
artifact: message.artifact,
status: message.status,
}
: {}),
};
// LangChain's StoredMessageData types content as string, but its codec supports native blocks.
return { type: message.getType(), data } as StoredMessage;
}
Loading