@artemiskit/core 0.3.0 → 0.4.1

package/src/tools/schema-validator.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'bun:test';
+import { validateToolArguments } from './schema-validator';
+
+const weatherSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['city'],
+  properties: { city: { type: 'string', minLength: 1 } },
+};
+
+describe('validateToolArguments', () => {
+  it('returns parsed arguments that satisfy the JSON schema', () => {
+    expect(validateToolArguments('{"city":"Lagos"}', weatherSchema)).toEqual({
+      valid: true,
+      arguments: { city: 'Lagos' },
+    });
+  });
+
+  it('rejects malformed JSON without echoing the arguments', () => {
+    expect(validateToolArguments('{city:Lagos}', weatherSchema)).toEqual({
+      valid: false,
+      error: { code: 'TOOL_ARGUMENTS_INVALID', message: 'Tool arguments must be valid JSON.' },
+    });
+  });
+
+  it('rejects arguments that fail the declared schema', () => {
+    const result = validateToolArguments('{"city":42}', weatherSchema);
+
+    expect(result.valid).toBe(false);
+    expect(result.error?.code).toBe('TOOL_ARGUMENTS_SCHEMA_INVALID');
+  });
+});

package/src/tools/schema-validator.ts

@@ -0,0 +1,56 @@
+import Ajv, { type ValidateFunction } from 'ajv';
+
+export interface ToolArgumentValidation {
+  valid: boolean;
+  arguments?: Record<string, unknown>;
+  error?: { code: 'TOOL_ARGUMENTS_INVALID' | 'TOOL_ARGUMENTS_SCHEMA_INVALID'; message: string };
+}
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validators = new WeakMap<object, ValidateFunction>();
+
+function getValidator(schema: Record<string, unknown>): ValidateFunction {
+  const cached = validators.get(schema);
+  if (cached) return cached;
+  const validator = ajv.compile(schema);
+  validators.set(schema, validator);
+  return validator;
+}
+
+export function validateToolArguments(
+  rawArguments: string,
+  schema: Record<string, unknown>
+): ToolArgumentValidation {
+  let args: unknown;
+  try {
+    args = JSON.parse(rawArguments);
+  } catch {
+    return {
+      valid: false,
+      error: { code: 'TOOL_ARGUMENTS_INVALID', message: 'Tool arguments must be valid JSON.' },
+    };
+  }
+
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return {
+      valid: false,
+      error: { code: 'TOOL_ARGUMENTS_INVALID', message: 'Tool arguments must be a JSON object.' },
+    };
+  }
+
+  const validator = getValidator(schema);
+  if (!validator(args)) {
+    const details = (validator.errors ?? [])
+      .map((error) => `${error.instancePath || '/'} ${error.message ?? 'is invalid'}`)
+      .join('; ');
+    return {
+      valid: false,
+      error: {
+        code: 'TOOL_ARGUMENTS_SCHEMA_INVALID',
+        message: `Tool arguments do not match the schema: ${details}`,
+      },
+    };
+  }
+
+  return { valid: true, arguments: args as Record<string, unknown> };
+}

package/src/tools/types.ts

@@ -0,0 +1,80 @@
+import type { ToolCall, ToolDefinition } from '../adapters/types';
+
+export type ToolLoopTerminationReason =
+  | 'completed'
+  | 'max_steps'
+  | 'timeout'
+  | 'duplicate_call'
+  | 'invalid_arguments'
+  | 'unknown_tool'
+  | 'tool_error';
+
+export interface ToolLoopPolicy {
+  enabled: boolean;
+  maxSteps: number;
+  timeoutMs: number;
+  maxToolResultBytes: number;
+  rejectDuplicateCalls: boolean;
+}
+
+export const DEFAULT_TOOL_LOOP_POLICY: ToolLoopPolicy = {
+  enabled: false,
+  maxSteps: 5,
+  timeoutMs: 60_000,
+  maxToolResultBytes: 32_768,
+  rejectDuplicateCalls: true,
+};
+
+export interface ToolExecutionContext {
+  caseId: string;
+  step: number;
+}
+
+export interface ToolExecutionError {
+  code:
+    | 'TOOL_ARGUMENTS_INVALID'
+    | 'TOOL_ARGUMENTS_SCHEMA_INVALID'
+    | 'TOOL_UNKNOWN'
+    | 'TOOL_FIXTURE_NOT_FOUND'
+    | 'TOOL_EXECUTION_FAILED'
+    | 'TOOL_RESULT_TOO_LARGE';
+  message: string;
+}
+
+export interface ToolExecutionResult {
+  status: 'success' | 'error';
+  result?: unknown;
+  error?: ToolExecutionError;
+}
+
+export interface ToolExecutor {
+  execute(call: ToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+}
+
+export interface ToolTraceEntry {
+  step: number;
+  toolCall: ToolCall;
+  result?: unknown;
+  error?: ToolExecutionError;
+  latencyMs: number;
+}
+
+export interface ToolLoopSummary {
+  status: 'completed' | 'error';
+  steps: number;
+  terminationReason: ToolLoopTerminationReason;
+}
+
+export interface ToolFixture {
+  when?: Record<string, unknown>;
+  result?: unknown;
+  error?: string;
+}
+
+export type ToolFixtures = Record<string, ToolFixture[]>;
+
+export interface FixtureExecutorOptions {
+  tools: ToolDefinition[];
+  fixtures: ToolFixtures;
+  maxToolResultBytes?: number;
+}