Skip to content

Build and run agents you can see, understand and trust.

14.0 KB
Raw Blame
import Ajv2020 from 'ajv/dist/2020.js';

import { CLIENT_BUILTIN_TOOL_NAMES } from './client-external-tool-definitions.ts';
import type { ClientExternalToolDefinition } from '../api/types.ts';

export const CLIENT_EXTERNAL_TOOL_STORAGE_KEY = 'agentscope.client-external-tools.v1';

const CLIENT_TOOL_PREFIX = 'client__';
const MAX_TOOL_NAME_LENGTH = 64;
const MAX_DISPLAY_NAME_LENGTH = 80;
const MAX_DESCRIPTION_LENGTH = 2000;
const MAX_SCHEMA_BYTES = 64 * 1024;
const MAX_CLIENT_TOOLS = 16;
const TOOL_NAME_PATTERN = /^client__[a-zA-Z0-9_-]+$/;
const REFERENCE_KEYWORDS = new Set(['$ref', '$dynamicRef', '$recursiveRef']);
const SUPPORTED_SCHEMA_URIS = new Set([
	'https://json-schema.org/draft/2020-12/schema',
	'https://json-schema.org/draft/2020-12/schema#',
]);
const SINGLE_SCHEMA_KEYWORDS = new Set([
	'additionalProperties',
	'unevaluatedProperties',
	'propertyNames',
	'items',
	'contains',
	'unevaluatedItems',
	'not',
	'if',
	'then',
	'else',
	'contentSchema',
]);
const SCHEMA_MAP_KEYWORDS = new Set([
	'$defs',
	'definitions',
	'properties',
	'patternProperties',
	'dependentSchemas',
	'dependencies',
]);
const SCHEMA_ARRAY_KEYWORDS = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);

export interface CustomClientExternalTool {
	display_name: string;
	definition: ClientExternalToolDefinition;
}

export interface CustomClientExternalToolDraft {
	displayName: string;
	name: string;
	description: string;
	inputSchema: string;
}

export type CustomToolValidationField = 'displayName' | 'name' | 'description' | 'inputSchema';

export type CustomToolValidationCode =
	| 'required'
	| 'displayNameTooLong'
	| 'invalidName'
	| 'duplicateName'
	| 'descriptionTooLong'
	| 'invalidJson'
	| 'invalidSchema'
	| 'schemaMustBeObject'
	| 'schemaPropertiesRequired'
	| 'remoteReference'
	| 'schemaTooLarge'
	| 'toolLimit';

export type CustomToolValidationError = {
	field: CustomToolValidationField;
	code: CustomToolValidationCode;
};

export type CustomToolValidationResult =
	| { ok: true; tool: CustomClientExternalTool }
	| { ok: false; error: CustomToolValidationError };

export interface ClientExternalToolStoreState {
	version: 1;
	customTools: CustomClientExternalTool[];
	selections: Record<string, string[]>;
}

const EMPTY_STATE: ClientExternalToolStoreState = {
	version: 1,
	customTools: [],
	selections: {},
};

const builtInNames = new Set<string>(CLIENT_BUILTIN_TOOL_NAMES);
const listeners = new Set<() => void>();
let storageListenerAttached = false;
const schemaValidator = new Ajv2020({ strict: false });

function isRecord(value: unknown): value is Record<string, unknown> {
	return value !== null && typeof value === 'object' && !Array.isArray(value);
}

function isDefinition(value: unknown): value is ClientExternalToolDefinition {
	return (
		isRecord(value) &&
		typeof value.name === 'string' &&
		typeof value.description === 'string' &&
		(value.read_only === undefined || typeof value.read_only === 'boolean') &&
		isRecord(value.input_schema)
	);
}

function isCustomTool(value: unknown): value is CustomClientExternalTool {
	return (
		isRecord(value) && typeof value.display_name === 'string' && isDefinition(value.definition)
	);
}

function sanitizeCustomTools(value: unknown): CustomClientExternalTool[] {
	if (!Array.isArray(value)) return [];
	const tools: CustomClientExternalTool[] = [];
	const occupiedNames = new Set(builtInNames);
	for (const candidate of value) {
		if (!isCustomTool(candidate) || tools.length + builtInNames.size >= MAX_CLIENT_TOOLS) {
			continue;
		}
		const validated = validateCustomClientToolDraft(
			{
				displayName: candidate.display_name,
				name: candidate.definition.name,
				description: candidate.definition.description,
				inputSchema: JSON.stringify(candidate.definition.input_schema),
			},
			occupiedNames,
		);
		if (!validated.ok || validated.tool.definition.name !== candidate.definition.name) continue;
		tools.push(validated.tool);
		occupiedNames.add(validated.tool.definition.name);
	}
	return tools;
}

function makeSessionKey(agentId: string, sessionId: string): string {
	return JSON.stringify([agentId, sessionId]);
}

function readStoredState(): ClientExternalToolStoreState {
	if (typeof window === 'undefined') return EMPTY_STATE;

	try {
		return parseClientExternalToolStoreState(
			window.localStorage.getItem(CLIENT_EXTERNAL_TOOL_STORAGE_KEY),
		);
	} catch {
		return EMPTY_STATE;
	}
}

let snapshot = readStoredState();

function emit(nextState: ClientExternalToolStoreState): void {
	snapshot = nextState;
	try {
		window.localStorage.setItem(CLIENT_EXTERNAL_TOOL_STORAGE_KEY, JSON.stringify(nextState));
	} catch {
		// Keep the current tab functional when storage is unavailable or full.
	}
	listeners.forEach((listener) => listener());
}

function attachStorageListener(): void {
	if (storageListenerAttached || typeof window === 'undefined') return;
	storageListenerAttached = true;
	window.addEventListener('storage', (event) => {
		if (event.key !== CLIENT_EXTERNAL_TOOL_STORAGE_KEY) return;
		snapshot = parseClientExternalToolStoreState(event.newValue);
		listeners.forEach((listener) => listener());
	});
}

function* schemaNodes(value: Record<string, unknown>): Generator<Record<string, unknown>> {
	// Check explicit schema positions here; the server also resolves references.
	const pending: unknown[] = [value];
	while (pending.length) {
		const node = pending.pop();
		if (!isRecord(node)) continue;
		yield node;
		for (const [keyword, child] of Object.entries(node)) {
			if (SINGLE_SCHEMA_KEYWORDS.has(keyword)) {
				pending.push(child);
			} else if (SCHEMA_MAP_KEYWORDS.has(keyword) && isRecord(child)) {
				for (const item of Object.values(child)) pending.push(item);
			} else if (SCHEMA_ARRAY_KEYWORDS.has(keyword) && Array.isArray(child)) {
				for (const item of child) pending.push(item);
			}
		}
	}
}

function containsRemoteReference(value: Record<string, unknown>): boolean {
	for (const node of schemaNodes(value)) {
		if (
			Object.entries(node).some(
				([key, child]) =>
					REFERENCE_KEYWORDS.has(key) &&
					typeof child === 'string' &&
					!child.startsWith('#'),
			)
		)
			return true;
	}
	return false;
}

function schemaByteLength(schema: Record<string, unknown>): number {
	return new TextEncoder().encode(JSON.stringify(schema)).byteLength;
}

function containsUnsupportedSchemaDialect(value: Record<string, unknown>): boolean {
	for (const node of schemaNodes(value)) {
		if (typeof node.$schema === 'string' && !SUPPORTED_SCHEMA_URIS.has(node.$schema))
			return true;
	}
	return false;
}

function isValidDraft202012Schema(schema: Record<string, unknown>): boolean {
	if ('$schema' in schema && typeof schema.$schema !== 'string') return false;
	const schemaToValidate = { ...schema };
	delete schemaToValidate.$schema;
	try {
		// Reject dialect switches before using the fixed Draft 2020-12 validator.
		if (containsUnsupportedSchemaDialect(schema)) return false;
		return schemaValidator.validateSchema(schemaToValidate) === true;
	} catch {
		return false;
	}
}

export function normalizeClientToolName(name: string): string {
	const trimmed = name.trim();
	return trimmed.startsWith(CLIENT_TOOL_PREFIX) ? trimmed : `${CLIENT_TOOL_PREFIX}${trimmed}`;
}

export function parseClientExternalToolStoreState(
	serialized: string | null,
): ClientExternalToolStoreState {
	if (!serialized) return EMPTY_STATE;

	try {
		const value: unknown = JSON.parse(serialized);
		if (!isRecord(value) || value.version !== 1) return EMPTY_STATE;

		const customTools = sanitizeCustomTools(value.customTools);
		const selections: Record<string, string[]> = {};
		if (isRecord(value.selections)) {
			for (const [key, names] of Object.entries(value.selections)) {
				if (Array.isArray(names)) {
					selections[key] = names
						.filter(
							(name, index): name is string =>
								typeof name === 'string' &&
								(builtInNames.has(name) || TOOL_NAME_PATTERN.test(name)) &&
								names.indexOf(name) === index,
						)
						.slice(0, MAX_CLIENT_TOOLS);
				}
			}
		}

		return { version: 1, customTools, selections };
	} catch {
		return EMPTY_STATE;
	}
}

export function validateCustomClientToolDraft(
	draft: CustomClientExternalToolDraft,
	occupiedNames: ReadonlySet<string> = builtInNames,
): CustomToolValidationResult {
	const displayName = draft.displayName.trim();
	if (!displayName) return { ok: false, error: { field: 'displayName', code: 'required' } };
	if (displayName.length > MAX_DISPLAY_NAME_LENGTH) {
		return { ok: false, error: { field: 'displayName', code: 'displayNameTooLong' } };
	}

	const name = normalizeClientToolName(draft.name);
	if (name.length > MAX_TOOL_NAME_LENGTH || !TOOL_NAME_PATTERN.test(name)) {
		return { ok: false, error: { field: 'name', code: 'invalidName' } };
	}
	if (occupiedNames.has(name)) {
		return { ok: false, error: { field: 'name', code: 'duplicateName' } };
	}

	const description = draft.description.trim();
	if (!description) return { ok: false, error: { field: 'description', code: 'required' } };
	if (description.length > MAX_DESCRIPTION_LENGTH) {
		return { ok: false, error: { field: 'description', code: 'descriptionTooLong' } };
	}

	let schema: unknown;
	try {
		schema = JSON.parse(draft.inputSchema);
	} catch {
		return { ok: false, error: { field: 'inputSchema', code: 'invalidJson' } };
	}
	if (!isRecord(schema) || schema.type !== 'object') {
		return { ok: false, error: { field: 'inputSchema', code: 'schemaMustBeObject' } };
	}
	if (!isRecord(schema.properties)) {
		return { ok: false, error: { field: 'inputSchema', code: 'schemaPropertiesRequired' } };
	}
	if (!isValidDraft202012Schema(schema)) {
		return { ok: false, error: { field: 'inputSchema', code: 'invalidSchema' } };
	}
	if (containsRemoteReference(schema)) {
		return { ok: false, error: { field: 'inputSchema', code: 'remoteReference' } };
	}
	if (schemaByteLength(schema) > MAX_SCHEMA_BYTES) {
		return { ok: false, error: { field: 'inputSchema', code: 'schemaTooLarge' } };
	}

	return {
		ok: true,
		tool: {
			display_name: displayName,
			definition: { name, description, read_only: false, input_schema: schema },
		},
	};
}

export function subscribeClientExternalToolStore(listener: () => void): () => void {
	attachStorageListener();
	listeners.add(listener);
	return () => listeners.delete(listener);
}

export function getClientExternalToolStoreSnapshot(): ClientExternalToolStoreState {
	return snapshot;
}

export function getClientExternalToolServerSnapshot(): ClientExternalToolStoreState {
	return EMPTY_STATE;
}

export function getEnabledClientExternalToolNames(
	agentId: string | null,
	sessionId: string | null,
	state: ClientExternalToolStoreState = snapshot,
): string[] {
	if (!agentId || !sessionId) return [];
	const stored = state.selections[makeSessionKey(agentId, sessionId)];
	if (!stored) return [...builtInNames];
	const availableNames = new Set([
		...builtInNames,
		...state.customTools.map((tool) => tool.definition.name),
	]);
	return stored.filter((name) => availableNames.has(name));
}

export function getEnabledClientExternalToolDefinitions(
	agentId: string,
	sessionId: string,
	state: ClientExternalToolStoreState = snapshot,
): ClientExternalToolDefinition[] {
	const definitions = state.customTools.map((tool) => tool.definition);
	const byName = new Map(definitions.map((definition) => [definition.name, definition]));
	return getEnabledClientExternalToolNames(agentId, sessionId, state)
		.map((name) => byName.get(name))
		.filter((definition): definition is ClientExternalToolDefinition => Boolean(definition));
}

export function getEnabledClientBuiltinTools(
	agentId: string,
	sessionId: string,
	state: ClientExternalToolStoreState = snapshot,
): Array<(typeof CLIENT_BUILTIN_TOOL_NAMES)[number]> {
	const enabled = new Set(getEnabledClientExternalToolNames(agentId, sessionId, state));
	return CLIENT_BUILTIN_TOOL_NAMES.filter((name) => enabled.has(name));
}

export function setClientExternalToolEnabled(
	agentId: string,
	sessionId: string,
	toolName: string,
	enabled: boolean,
): void {
	const current = new Set(getEnabledClientExternalToolNames(agentId, sessionId));
	if (enabled) current.add(toolName);
	else current.delete(toolName);
	emit({
		...snapshot,
		selections: {
			...snapshot.selections,
			[makeSessionKey(agentId, sessionId)]: [...current],
		},
	});
}

export function clearClientExternalToolSelection(agentId: string, sessionId: string): void {
	const key = makeSessionKey(agentId, sessionId);
	if (!(key in snapshot.selections)) return;
	const selections = { ...snapshot.selections };
	delete selections[key];
	emit({ ...snapshot, selections });
}

export function saveCustomClientExternalTool(
	draft: CustomClientExternalToolDraft,
	originalName: string | null,
	agentId: string | null,
	sessionId: string | null,
): CustomToolValidationResult {
	if (
		!originalName &&
		CLIENT_BUILTIN_TOOL_NAMES.length + snapshot.customTools.length >= MAX_CLIENT_TOOLS
	) {
		return { ok: false, error: { field: 'name', code: 'toolLimit' } };
	}

	const occupiedNames = new Set([
		...builtInNames,
		...snapshot.customTools
			.map((tool) => tool.definition.name)
			.filter((name) => name !== originalName),
	]);
	const validated = validateCustomClientToolDraft(draft, occupiedNames);
	if (!validated.ok) return validated;

	const nextName = validated.tool.definition.name;
	const customTools = originalName
		? snapshot.customTools.map((tool) =>
				tool.definition.name === originalName ? validated.tool : tool,
			)
		: [...snapshot.customTools, validated.tool];
	const selections = Object.fromEntries(
		Object.entries(snapshot.selections).map(([key, names]) => [
			key,
			names.map((name) => (name === originalName ? nextName : name)),
		]),
	);
	if (!originalName && agentId && sessionId) {
		const key = makeSessionKey(agentId, sessionId);
		selections[key] = [...getEnabledClientExternalToolNames(agentId, sessionId), nextName];
	}

	emit({ version: 1, customTools, selections });
	return validated;
}

export function deleteCustomClientExternalTool(toolName: string): void {
	emit({
		version: 1,
		customTools: snapshot.customTools.filter((tool) => tool.definition.name !== toolName),
		selections: Object.fromEntries(
			Object.entries(snapshot.selections).map(([key, names]) => [
				key,
				names.filter((name) => name !== toolName),
			]),
		),
	});
}