thumbgate 1.28.4 → 1.29.2

package/scripts/tool-contract-validator.js

@@ -2,75 +2,303 @@
 
 /**
  * Tool Contract Validator
- * Validates tool arguments against the tool's inputSchema.
+ *
+ * A dependency-free JSON Schema subset for tool arguments and structured
+ * outputs. The validator intentionally fails closed for unsupported schema
+ * shapes used at an agent boundary instead of silently accepting them.
  */
+
+const FORMAT_CHECKS = Object.freeze({
+  'date-time': (value) => !Number.isNaN(Date.parse(value)) && /T/.test(value),
+  email: isEmail,
+  uri: (value) => {
+    try {
+      new URL(value);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+});
+
 function validateToolContract(schema, args) {
+  if (!schema) return { valid: true, errors: [] };
   const errors = [];
-  if (!schema) return { valid: true, errors };
+  validateValue(schema, args, '', errors);
+  return { valid: errors.length === 0, errors };
+}
 
-  if (schema.type === 'object') {
-    if (typeof args !== 'object' || args === null || Array.isArray(args)) {
-      errors.push(`Expected object, got ${args === null ? 'null' : Array.isArray(args) ? 'array' : typeof args}`);
-      return { valid: false, errors };
+function validateStructuredOutput(output, schema) {
+  let value = output;
+  if (typeof output === 'string') {
+    try {
+      value = JSON.parse(output);
+    } catch (err) {
+      return {
+        valid: false,
+        errors: [`Structured output must be valid JSON: ${err.message}`],
+        value: null,
+      };
     }
+  }
+  const result = validateToolContract(schema, value);
+  return { ...result, value };
+}
+
+function validateConstant(schema, value, path, errors) {
+  if (schema.const !== undefined && !deepEqual(value, schema.const)) {
+    errors.push(`${label(path)} must equal ${display(schema.const)} (got ${display(value)})`);
+  }
+}
+
+function validateEnum(schema, value, path, errors) {
+  if (!Array.isArray(schema.enum) || schema.enum.some((entry) => deepEqual(entry, value))) return;
+  if (path && schema.type === 'string') {
+    errors.push(`Parameter '${path}' must be one of [${schema.enum.join(', ')}] (got '${value}')`);
+    return;
+  }
+  errors.push(`${label(path)} must be one of [${schema.enum.map(display).join(', ')}] (got ${display(value)})`);
+}
+
+function validateValue(schema, value, path, errors) {
+  if (schema === true || !schema) return;
+  if (schema === false) {
+    errors.push(`${label(path)} is disallowed by schema`);
+    return;
+  }
+
+  validateConstant(schema, value, path, errors);
+  validateEnum(schema, value, path, errors);
+
+  validateCombinators(schema, value, path, errors);
+
+  if (value === undefined) return;
+  const allowedTypes = normalizeTypes(schema.type);
+  if (allowedTypes.length > 0 && !allowedTypes.some((type) => matchesType(type, value))) {
+    errors.push(typeError(path, allowedTypes, value));
+    return;
+  }
+
+  if (value === null) return;
+  const actualType = jsonType(value);
+  if (actualType === 'object') validateObject(schema, value, path, errors);
+  if (actualType === 'array') validateArray(schema, value, path, errors);
+  if (actualType === 'string') validateString(schema, value, path, errors);
+  if (actualType === 'number' || actualType === 'integer') validateNumber(schema, value, path, errors);
+}
+
+function validateCombinators(schema, value, path, errors) {
+  if (Array.isArray(schema.allOf)) {
+    for (const child of schema.allOf) validateValue(child, value, path, errors);
+  }
+  if (Array.isArray(schema.anyOf)) {
+    const matches = schema.anyOf.filter((child) => validateChild(child, value).valid).length;
+    if (matches === 0) errors.push(`${label(path)} must match at least one anyOf schema`);
+  }
+  if (Array.isArray(schema.oneOf)) {
+    const matches = schema.oneOf.filter((child) => validateChild(child, value).valid).length;
+    if (matches !== 1) errors.push(`${label(path)} must match exactly one oneOf schema (matched ${matches})`);
+  }
+  if (schema.not && validateChild(schema.not, value).valid) {
+    errors.push(`${label(path)} matches a forbidden schema`);
+  }
+}
+
+function validateChild(schema, value) {
+  const errors = [];
+  validateValue(schema, value, '', errors);
+  return { valid: errors.length === 0, errors };
+}
+
+function validatePropertyCount(schema, keys, path, errors) {
+  if (Number.isFinite(schema.minProperties) && keys.length < schema.minProperties) {
+    errors.push(`${label(path)} must have at least ${schema.minProperties} properties`);
+  }
+  if (Number.isFinite(schema.maxProperties) && keys.length > schema.maxProperties) {
+    errors.push(`${label(path)} must have at most ${schema.maxProperties} properties`);
+  }
+}
+
+function validateRequiredProperties(schema, value, path, errors) {
+  for (const required of schema.required || []) {
+    if (value[required] === undefined || value[required] === null || value[required] === '') {
+      const requiredPath = joinPath(path, required);
+      errors.push(path
+        ? `Parameter '${path}': Missing required parameter: '${required}'`
+        : `Missing required parameter: '${required}'`);
+      if (path && requiredPath === path) break;
+    }
+  }
+}
+
+function validateKnownProperties(schema, value, path, errors) {
+  const properties = schema.properties || {};
+  for (const [key, childSchema] of Object.entries(properties)) {
+    if (value[key] === undefined) continue;
+    validateValue(childSchema, value[key], joinPath(path, key), errors);
+  }
+}
+
+function validateAdditionalProperties(schema, value, keys, path, errors) {
+  const properties = schema.properties || {};
+  for (const key of keys) {
+    if (Object.hasOwn(properties, key)) continue;
+    if (schema.additionalProperties === false) {
+      errors.push(`Unexpected parameter: '${joinPath(path, key)}'`);
+    } else if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+      validateValue(schema.additionalProperties, value[key], joinPath(path, key), errors);
+    }
+  }
+}
+
+function validateObject(schema, value, path, errors) {
+  const keys = Object.keys(value);
+  validatePropertyCount(schema, keys, path, errors);
+  validateRequiredProperties(schema, value, path, errors);
+  validateKnownProperties(schema, value, path, errors);
+  validateAdditionalProperties(schema, value, keys, path, errors);
+}
 
-    // Check required fields
-    if (Array.isArray(schema.required)) {
-      for (const req of schema.required) {
-        if (args[req] === undefined || args[req] === null || args[req] === '') {
-          errors.push(`Missing required parameter: '${req}'`);
-        }
-      }
+function validateArray(schema, value, path, errors) {
+  if (Number.isFinite(schema.minItems) && value.length < schema.minItems) {
+    errors.push(`${label(path)} must contain at least ${schema.minItems} items`);
+  }
+  if (Number.isFinite(schema.maxItems) && value.length > schema.maxItems) {
+    errors.push(`${label(path)} must contain at most ${schema.maxItems} items`);
+  }
+  if (schema.uniqueItems === true) {
+    const serialized = value.map(stableStringify);
+    if (new Set(serialized).size !== serialized.length) {
+      errors.push(`${label(path)} must contain unique items`);
     }
+  }
+  if (schema.items) {
+    value.forEach((entry, index) => validateValue(schema.items, entry, `${path}[${index}]`, errors));
+  }
+}
 
-    // Check properties
-    if (schema.properties) {
-      for (const [key, propSchema] of Object.entries(schema.properties)) {
-        const value = args[key];
-        if (value === undefined || value === null) continue; // Optional field not provided
-
-        const valType = typeof value;
-        if (propSchema.type === 'string') {
-          if (valType !== 'string') {
-            errors.push(`Parameter '${key}' must be a string (got ${valType})`);
-          } else if (Array.isArray(propSchema.enum)) {
-            if (!propSchema.enum.includes(value)) {
-              errors.push(`Parameter '${key}' must be one of [${propSchema.enum.join(', ')}] (got '${value}')`);
-            }
-          }
-        } else if (propSchema.type === 'number') {
-          if (valType !== 'number' || isNaN(value)) {
-            errors.push(`Parameter '${key}' must be a number (got ${valType})`);
-          }
-        } else if (propSchema.type === 'boolean') {
-          if (valType !== 'boolean') {
-            errors.push(`Parameter '${key}' must be a boolean (got ${valType})`);
-          }
-        } else if (propSchema.type === 'array') {
-          if (!Array.isArray(value)) {
-            errors.push(`Parameter '${key}' must be an array (got ${valType})`);
-          }
-        } else if (propSchema.type === 'object') {
-          if (valType !== 'object' || value === null || Array.isArray(value)) {
-            errors.push(`Parameter '${key}' must be an object (got ${valType})`);
-          } else {
-            // Recurse for nested objects
-            const subRes = validateToolContract(propSchema, value);
-            if (!subRes.valid) {
-              for (const err of subRes.errors) {
-                errors.push(`Parameter '${key}': ${err}`);
-              }
-            }
-          }
-        }
-      }
+function validateString(schema, value, path, errors) {
+  if (Number.isFinite(schema.minLength) && value.length < schema.minLength) {
+    errors.push(`${label(path)} must contain at least ${schema.minLength} characters`);
+  }
+  if (Number.isFinite(schema.maxLength) && value.length > schema.maxLength) {
+    errors.push(`${label(path)} must contain at most ${schema.maxLength} characters`);
+  }
+  if (schema.pattern) {
+    let regex;
+    try {
+      regex = new RegExp(schema.pattern);
+    } catch {
+      errors.push(`${label(path)} uses invalid schema pattern '${schema.pattern}'`);
+      return;
     }
+    if (!regex.test(value)) errors.push(`${label(path)} must match pattern ${schema.pattern}`);
+  }
+  if (schema.format && FORMAT_CHECKS[schema.format] && !FORMAT_CHECKS[schema.format](value)) {
+    errors.push(`${label(path)} must match format ${schema.format}`);
   }
+}
+
+function validateNumber(schema, value, path, errors) {
+  if (Number.isFinite(schema.minimum) && value < schema.minimum) {
+    errors.push(`${label(path)} must be >= ${schema.minimum}`);
+  }
+  if (Number.isFinite(schema.maximum) && value > schema.maximum) {
+    errors.push(`${label(path)} must be <= ${schema.maximum}`);
+  }
+  if (Number.isFinite(schema.exclusiveMinimum) && value <= schema.exclusiveMinimum) {
+    errors.push(`${label(path)} must be > ${schema.exclusiveMinimum}`);
+  }
+  if (Number.isFinite(schema.exclusiveMaximum) && value >= schema.exclusiveMaximum) {
+    errors.push(`${label(path)} must be < ${schema.exclusiveMaximum}`);
+  }
+  if (Number.isFinite(schema.multipleOf) && !isMultipleOf(value, schema.multipleOf)) {
+    errors.push(`${label(path)} must be a multiple of ${schema.multipleOf}`);
+  }
+}
+
+function normalizeTypes(type) {
+  if (!type) return [];
+  return Array.isArray(type) ? type : [type];
+}
+
+function matchesType(type, value) {
+  if (type === 'null') return value === null;
+  if (type === 'array') return Array.isArray(value);
+  if (type === 'object') return value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (type === 'integer') return Number.isInteger(value);
+  if (type === 'number') return typeof value === 'number' && Number.isFinite(value);
+  return typeof value === type;
+}
+
+function isEmail(value) {
+  if (typeof value !== 'string' || /\s/.test(value)) return false;
+  const atIndex = value.indexOf('@');
+  if (atIndex <= 0 || atIndex !== value.lastIndexOf('@')) return false;
+  const domain = value.slice(atIndex + 1);
+  const dotIndex = domain.lastIndexOf('.');
+  return dotIndex > 0 && dotIndex < domain.length - 1;
+}
+
+function jsonType(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (Number.isInteger(value)) return 'integer';
+  if (typeof value === 'number') return 'number';
+  return typeof value;
+}
+
+function typeError(path, types, value) {
+  const expected = types.length === 1 ? types[0] : types.join(' or ');
+  const actual = actualTypeName(value);
+  if (!path) return `Expected ${expected}, got ${actual}`;
+  return `Parameter '${path}' must be ${article(expected)} ${expected} (got ${actual})`;
+}
+
+function actualTypeName(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+function article(value) {
+  return /^[aeiou]/i.test(value) ? 'an' : 'a';
+}
+
+function label(path) {
+  return path ? `Parameter '${path}'` : 'Value';
+}
+
+function joinPath(parent, child) {
+  return parent ? `${parent}.${child}` : child;
+}
+
+function display(value) {
+  if (typeof value === 'string') return `'${value}'`;
+  return stableStringify(value);
+}
+
+function stableStringify(value) {
+  if (!value || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(value).sort((left, right) => left.localeCompare(right));
+  const properties = keys.map((key) => [
+    JSON.stringify(key),
+    stableStringify(value[key]),
+  ].join(':'));
+  return ['{', properties.join(','), '}'].join('');
+}
+
+function deepEqual(a, b) {
+  return stableStringify(a) === stableStringify(b);
+}
 
-  return {
-    valid: errors.length === 0,
-    errors,
-  };
+function isMultipleOf(value, multiple) {
+  const quotient = value / multiple;
+  return Math.abs(quotient - Math.round(quotient)) < Number.EPSILON * 10;
 }
 
-module.exports = { validateToolContract };
+module.exports = {
+  validateStructuredOutput,
+  validateToolContract,
+};

package/scripts/tool-registry.js

@@ -60,6 +60,79 @@ const GOAL_CONTRACT_SCHEMA = {
   },
 };
 
+const TASK_OUTCOME_INPUT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['taskId', 'goal', 'status', 'verification', 'toolCalls', 'policy', 'efficiency'],
+  properties: {
+    taskId: { type: 'string', minLength: 1 },
+    taskType: { type: 'string' },
+    goal: { type: 'string', minLength: 1 },
+    expectedOutcome: { type: 'string' },
+    status: { type: 'string', enum: ['completed', 'failed', 'partial', 'escalated'] },
+    verification: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['performed', 'passed', 'evidence'],
+      properties: {
+        performed: { type: 'boolean' },
+        passed: { type: 'boolean' },
+        verifier: { type: 'string' },
+        method: { type: 'string' },
+        evidence: { type: 'array', items: { type: 'string' } },
+        unsupportedClaims: { type: 'integer', minimum: 0 },
+      },
+    },
+    toolCalls: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['name', 'contractValid', 'allowed', 'succeeded', 'attempts'],
+        properties: {
+          name: { type: 'string' },
+          contractValid: { type: 'boolean' },
+          allowed: { type: 'boolean' },
+          succeeded: { type: 'boolean' },
+          attempts: { type: 'integer', minimum: 1 },
+          latencyMs: { type: 'number', minimum: 0 },
+          costUsd: { type: 'number', minimum: 0 },
+          sideEffect: { type: 'boolean' },
+          idempotencyKey: { type: 'string' },
+          duplicateSideEffect: { type: 'boolean' },
+        },
+      },
+    },
+    policy: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['violations', 'unsafeEscapes', 'falseBlocks'],
+      properties: {
+        violations: { type: 'integer', minimum: 0 },
+        unsafeEscapes: { type: 'integer', minimum: 0 },
+        falseBlocks: { type: 'integer', minimum: 0 },
+      },
+    },
+    failure: { type: 'object', additionalProperties: true },
+    escalation: { type: 'object', additionalProperties: true },
+    efficiency: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['latencyMs', 'costUsd'],
+      properties: {
+        latencyMs: { type: 'number', minimum: 0 },
+        costUsd: { type: 'number', minimum: 0 },
+        firstAttempt: { type: 'boolean' },
+      },
+    },
+    businessOutcome: { type: 'object', additionalProperties: true },
+    traceId: { type: 'string' },
+    idempotencyKey: { type: 'string' },
+    versions: { type: 'object', additionalProperties: true },
+    metadata: { type: 'object', additionalProperties: true },
+  },
+};
+
 const TOOLS = [
   readOnlyTool({
     name: 'capture_feedback',
@@ -969,6 +1042,76 @@ const TOOLS = [
       },
     },
   }),
+  destructiveTool({
+    name: 'record_task_outcome',
+    title: 'Record Verified Task Outcome',
+    description: 'Record an idempotent task-level outcome with verification evidence, tool correctness, policy behavior, latency, cost, and business KPI movement. A completed response without evidence is recorded as not working.',
+    inputSchema: TASK_OUTCOME_INPUT_SCHEMA,
+  }),
+  readOnlyTool({
+    name: 'get_task_outcomes',
+    title: 'Get Task Outcomes',
+    description: 'Read a task outcome by taskId or the most recent evidence-backed outcome receipts.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        taskId: { type: 'string' },
+        limit: { type: 'integer', minimum: 1, maximum: 100 },
+      },
+    },
+  }),
+  readOnlyTool({
+    name: 'get_agent_outcome_metrics',
+    title: 'Get Agent Outcome Metrics',
+    description: 'Compute transparent task, tool, safety, escalation, latency, cost, and business metrics from recorded task outcomes. Empty data returns insufficient_evidence.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {},
+    },
+  }),
+  destructiveTool({
+    name: 'request_human_escalation',
+    title: 'Request Human Escalation',
+    description: 'Create an idempotent, expiring human-review request with requester identity and evidence. Agents cannot approve their own requests.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['taskId', 'reason', 'requester', 'evidence'],
+      properties: {
+        taskId: { type: 'string', minLength: 1 },
+        reason: { type: 'string', minLength: 1 },
+        severity: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
+        requester: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['id', 'kind'],
+          properties: {
+            id: { type: 'string', minLength: 1 },
+            kind: { type: 'string', enum: ['agent', 'service', 'human'] },
+            displayName: { type: 'string' },
+          },
+        },
+        evidence: { type: 'array', minItems: 1, items: { type: 'string', minLength: 1 } },
+        ttlMs: { type: 'number', minimum: 1 },
+        idempotencyKey: { type: 'string' },
+      },
+    },
+  }),
+  readOnlyTool({
+    name: 'list_human_escalations',
+    title: 'List Human Escalations',
+    description: 'List auditable human-escalation state. Approval decisions are deliberately absent from the agent tool surface.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        status: { type: 'string', enum: ['pending', 'approved', 'rejected', 'cancelled', 'expired'] },
+        limit: { type: 'integer', minimum: 1, maximum: 100 },
+      },
+    },
+  }),
   readOnlyTool({
     name: 'verify_claim',
     description: 'Check whether a claim has enough tracked evidence before the agent asserts it.',

package/scripts/vector-store.js

@@ -28,6 +28,7 @@ let _lastEmbeddingProfile = null;
 let _pipelineLoader = null;
 let _geminiEmbedderForTests = null;
 const TABLE_NAME = 'thumbgate_memories';
+const FEATURE_HASH_DIMENSIONS = 384;
 
 async function getLanceDB() {
   if (!_lancedb) {
@@ -69,6 +70,58 @@ async function loadPipelineForProfile(profile) {
   return pipe;
 }
 
+function hasLocalTransformerProvider() {
+  if (_pipelineLoader) return true;
+  try {
+    require.resolve('@huggingface/transformers');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function fnv1a32(value) {
+  let hash = 0x811c9dc5;
+  const bytes = Buffer.from(String(value), 'utf8');
+  for (const byte of bytes) {
+    hash ^= byte;
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash;
+}
+
+function addHashedFeature(vector, feature, weight) {
+  const hash = fnv1a32(feature);
+  const index = hash % vector.length;
+  const sign = (hash & 0x80000000) === 0 ? 1 : -1;
+  vector[index] += sign * weight;
+}
+
+function embedWithFeatureHash(text) {
+  const vector = Array(FEATURE_HASH_DIMENSIONS).fill(0);
+  const tokens = String(text || '').toLowerCase().match(/[\p{L}\p{N}_-]+/gu) || [];
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    addHashedFeature(vector, `token:${token}`, 1);
+    if (index > 0) {
+      addHashedFeature(vector, `bigram:${tokens[index - 1]}:${token}`, 0.6);
+    }
+
+    const bounded = `^${token.slice(0, 64)}$`;
+    for (let offset = 0; offset <= bounded.length - 3; offset += 1) {
+      addHashedFeature(vector, `trigram:${bounded.slice(offset, offset + 3)}`, 0.3);
+    }
+  }
+
+  const norm = Math.sqrt(vector.reduce((sum, value) => sum + (value * value), 0));
+  if (norm === 0) {
+    vector[0] = 1;
+    return vector;
+  }
+  return vector.map((value) => value / norm);
+}
+
 async function getEmbeddingPipeline() {
   const resolved = resolveEmbeddingProfile();
   const report = writeModelFitReport(getFeedbackDir(), { resolved }).report;
@@ -247,12 +300,33 @@ async function embed(text, options = {}) {
       console.warn(`Gemini embedding fallback: ${geminiError.message}`);
     }
   }
-  const { pipe, profile } = await getEmbeddingPipeline();
-  const output = await pipe(truncateForEmbedding(text, profile.activeProfile.maxChars), {
-    pooling: 'mean',
-    normalize: true,
-  });
-  return Array.from(output.data); // Float32Array -> plain number[] for LanceDB Arrow serialization
+  if (hasLocalTransformerProvider()) {
+    try {
+      const { pipe, profile } = await getEmbeddingPipeline();
+      const output = await pipe(truncateForEmbedding(text, profile.activeProfile.maxChars), {
+        pooling: 'mean',
+        normalize: true,
+      });
+      return Array.from(output.data); // Float32Array -> plain number[] for LanceDB Arrow serialization
+    } catch (transformerError) {
+      console.warn(`Transformers.js embedding fallback: ${transformerError.message}`);
+    }
+  }
+
+  const vector = embedWithFeatureHash(text);
+  _lastEmbeddingProfile = {
+    generatedAt: new Date().toISOString(),
+    source: 'built-in',
+    activeProfile: {
+      id: 'feature-hash-v1',
+      model: 'ThumbGate feature hashing',
+      outputDimensionality: FEATURE_HASH_DIMENSIONS,
+      task: options.task || 'code retrieval',
+      rationale: 'Deterministic zero-dependency local text embedding.',
+    },
+    fallbackUsed: false,
+  };
+  return vector;
 }
 
 async function upsertFeedback(feedbackEvent) {
@@ -269,7 +343,8 @@ async function upsertFeedback(feedbackEvent) {
     feedbackEvent.whatWorked || '',
   ].filter(Boolean).join('. ');
 
-  // Embed is pure CPU/model work (transformers.js or stub) — deterministic
+  // Embed is pure CPU/model work (managed, optional Transformers.js, built-in,
+  // or stub) and deterministic for local providers.
   // for a given input, so no retry is needed here. Retry wraps the table
   // write below, which is the actual I/O failure surface.
   const vector = await embed(textForEmbedding, {
@@ -364,4 +439,5 @@ module.exports = {
   setLanceLoaderForTests,
   setGeminiEmbedderForTests,
   truncateForEmbedding,
+  embedWithFeatureHash,
 };