dsh-plugin-show-me-data 0.1.0

package/lib/host/tools/define-tool.js

@@ -0,0 +1,295 @@
+/**
+ * A dependency-free 'ToolDefinition' builder (docs/09 §4).
+ *
+ * The plugin deliberately does **not** import '@deepseek-ai/dsh-tools''s
+ * 'defineTool': this package is installed from the session workspace where the
+ * profile's 'node_modules' is not resolvable, and pulling a second copy of
+ * 'dsh-tools' into the process would fork the tool runtime. Building the
+ * definition shape by hand keeps the plugin dependency-free — the schema subset
+ * and the argument validation it would have provided are implemented here and
+ * covered by 'test/host/tools.test.js'.
+ *
+ * @module host/tools/define-tool
+ */
+
+/** JSON Schema keywords the registry enforces. */
+const ALLOWED_TYPES = ['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']
+
+/**
+ * Validate a raw JSON Schema node against the enforced subset.
+ *
+ * @param {any} schema - candidate schema.
+ * @param {string} path - path for error messages.
+ * @returns {string[]} violations (empty when supported).
+ */
+export function schemaViolations(schema, path = 'schema') {
+  const violations = []
+  if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+    return [`${path} must be an object`]
+  }
+  if (schema.type !== undefined && !ALLOWED_TYPES.includes(schema.type)) {
+    violations.push(`${path}.type must be one of ${ALLOWED_TYPES.join('/')}`)
+  }
+  if (schema.properties !== undefined) {
+    if (schema.type !== 'object') violations.push(`${path}.properties requires type: 'object'`)
+    if (schema.properties === null || typeof schema.properties !== 'object') {
+      violations.push(`${path}.properties must be an object`)
+    } else {
+      for (const [key, child] of Object.entries(schema.properties)) {
+        violations.push(...schemaViolations(child, `${path}.properties.${key}`))
+      }
+    }
+  }
+  if (schema.required !== undefined) {
+    if (!Array.isArray(schema.required) || schema.required.some((entry) => typeof entry !== 'string')) {
+      violations.push(`${path}.required must be an array of strings`)
+    }
+  }
+  if (schema.items !== undefined) {
+    if (schema.type !== 'array') violations.push(`${path}.items requires type: 'array'`)
+    violations.push(...schemaViolations(schema.items, `${path}.items`))
+  } else if (schema.type === 'array') {
+    // An array without `items` is legal (unconstrained entries) but almost always
+    // an authoring slip, so it is reported as a warning-level violation only when
+    // the schema also declares nothing else. We keep it legal: several tools
+    // return genuinely heterogeneous arrays.
+  }
+  if (schema.enum !== undefined && !Array.isArray(schema.enum)) {
+    violations.push(`${path}.enum must be an array`)
+  }
+  if (schema.oneOf !== undefined) {
+    if (!Array.isArray(schema.oneOf) || schema.oneOf.length !== 1) {
+      // The registry's subset allows exactly-one `oneOf`; we never emit it, so a
+      // malformed one here is an author error worth reporting.
+      violations.push(`${path}.oneOf must be an array with exactly one entry`)
+    } else {
+      violations.push(...schemaViolations(schema.oneOf[0], `${path}.oneOf[0]`))
+    }
+  }
+  const known = new Set(['type', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const', 'oneOf', 'description', 'title', 'default', 'examples'])
+  for (const key of Object.keys(schema)) {
+    if (!known.has(key)) violations.push(`${path}.${key} is not a supported keyword`)
+  }
+  return violations
+}
+
+/**
+ * Validate a value against the JSON Schema subset.
+ *
+ * @param {any} schema - schema.
+ * @param {any} value - candidate value.
+ * @param {string} [path] - path for error messages.
+ * @returns {string[]} violations.
+ */
+export function valueViolations(schema, value, path = '') {
+  const violations = []
+  if (schema === undefined || schema === null) return violations
+  if (schema.oneOf !== undefined) {
+    const passes = schema.oneOf.filter((candidate) => valueViolations(candidate, value, path).length === 0)
+    if (passes.length !== 1) violations.push(`${path || 'value'} must match exactly one allowed shape`)
+    return violations
+  }
+  if (schema.enum !== undefined && !schema.enum.includes(value)) {
+    violations.push(`${path || 'value'} must be one of ${schema.enum.map((entry) => JSON.stringify(entry)).join(', ')}`)
+    return violations
+  }
+  if (schema.const !== undefined && value !== schema.const) {
+    violations.push(`${path || 'value'} must be ${JSON.stringify(schema.const)}`)
+    return violations
+  }
+  const type = schema.type
+  if (type === 'object') {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      violations.push(`${path || 'value'} must be an object`)
+      return violations
+    }
+    for (const key of schema.required ?? []) {
+      if (!(key in value)) violations.push(`${path ? `${path}.` : ''}${key} is required`)
+    }
+    const properties = schema.properties ?? {}
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!(key in properties)) violations.push(`${path ? `${path}.` : ''}${key} is not allowed`)
+      }
+    }
+    for (const [key, child] of Object.entries(properties)) {
+      if (key in value) violations.push(...valueViolations(child, value[key], `${path ? `${path}.` : ''}${key}`))
+    }
+    return violations
+  }
+  if (type === 'array') {
+    if (!Array.isArray(value)) {
+      violations.push(`${path || 'value'} must be an array`)
+      return violations
+    }
+    if (schema.items !== undefined) {
+      value.forEach((entry, index) => violations.push(...valueViolations(schema.items, entry, `${path}[${index}]`)))
+    }
+    return violations
+  }
+  if (type === 'string' && typeof value !== 'string') violations.push(`${path || 'value'} must be a string`)
+  if (type === 'number' && (typeof value !== 'number' || !Number.isFinite(value))) violations.push(`${path || 'value'} must be a finite number`)
+  if (type === 'integer' && !Number.isInteger(value)) violations.push(`${path || 'value'} must be an integer`)
+  if (type === 'boolean' && typeof value !== 'boolean') violations.push(`${path || 'value'} must be a boolean`)
+  if (type === 'null' && value !== null) violations.push(`${path || 'value'} must be null`)
+  return violations
+}
+
+/**
+ * Drop `undefined` object properties and array holes from a tool value.
+ *
+ * Arrays keep their length (a hole becomes `null`) so a point series never
+ * silently shifts; objects simply lose the absent keys, which is what
+ * `JSON.stringify` would have done anyway — except that the harness snapshots
+ * the live value, where an own property set to `undefined` is an error rather
+ * than an omission.
+ *
+ * @param {any} value - candidate value.
+ * @returns {any} a JSON-safe copy.
+ */
+export function dropUndefined(value) {
+  if (value === null || typeof value !== 'object') return value
+  if (Array.isArray(value)) {
+    return value.map((entry) => (entry === undefined ? null : dropUndefined(entry)))
+  }
+  /** @type {Record<string, any>} */
+  const out = {}
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry === undefined) continue
+    out[key] = dropUndefined(entry)
+  }
+  return out
+}
+
+/**
+ * Find the first value the harness's lossless-JSON boundary would reject.
+ *
+ * A tool body's canonical value is snapshotted by the registry before it is
+ * stored, rendered or sent to the model, and that snapshot accepts only ordinary
+ * arrays, plain objects and JSON scalars: `undefined`, `NaN`, `Infinity`,
+ * `-0`, sparse arrays, `Date`, class instances and cycles are all refused. When
+ * that happens the model sees nothing but `value is not lossless JSON`, with no
+ * hint of which field caused it — so the plugin checks the same rule first and
+ * names the offending path itself.
+ *
+ * @param {any} value - candidate value.
+ * @param {string} [path] - path of `value`, for the message.
+ * @param {Set<object>} [seen] - ancestors on the current path.
+ * @returns {string|undefined} the offending path.
+ */
+export function findNonLossless(value, path = 'value', seen = new Set()) {
+  if (value === null) return undefined
+  const type = typeof value
+  if (type === 'string' || type === 'boolean') return undefined
+  if (type === 'number') {
+    if (!Number.isFinite(value)) return `${path} is ${String(value)} (neither is JSON)`
+    if (Object.is(value, -0)) return `${path} is -0 (not lossless)`
+    return undefined
+  }
+  if (type === 'undefined') return `${path} is undefined (dropped by JSON, refused at the boundary)`
+  if (type === 'bigint' || type === 'function' || type === 'symbol') return `${path} is a ${type}`
+  if (seen.has(value)) return `${path} is a cycle`
+  seen.add(value)
+  try {
+    if (Array.isArray(value)) {
+      for (let index = 0; index < value.length; index += 1) {
+        if (!Object.prototype.hasOwnProperty.call(value, index)) return `${path}[${index}] is a hole (sparse array)`
+        const found = findNonLossless(value[index], `${path}[${index}]`, seen)
+        if (found !== undefined) return found
+      }
+      return undefined
+    }
+    const prototype = Object.getPrototypeOf(value)
+    if (prototype !== Object.prototype && prototype !== null) {
+      return `${path} is a ${value?.constructor?.name ?? 'non-plain object'} (only plain objects survive)`
+    }
+    for (const key of Object.keys(value)) {
+      const found = findNonLossless(value[key], `${path}.${key}`, seen)
+      if (found !== undefined) return found
+    }
+    return undefined
+  } finally {
+    seen.delete(value)
+  }
+}
+
+/**
+ * Build a 'ToolDefinition' the registry accepts.
+ *
+ * @param {object} options - tool options.
+ * @param {string} options.name - tool name.
+ * @param {string} options.description - model-facing description.
+ * @param {Record<string, any>} options.parameters - argument JSON Schema (object root).
+ * @param {any} options.outputSchema - canonical output JSON Schema.
+ * @param {(args: any, value: any) => Array<{ type: string, text: string }>} options.render - content projection.
+ * @param {(args: any, exec: any) => Promise<any>} options.execute - tool body.
+ * @param {number} [options.timeoutMs] - cooperative timeout budget.
+ * @param {boolean} [options.concurrencySafe] - whether parallel dispatch is allowed.
+ * @returns {object} tool definition.
+ */
+export function defineTool({ name, description, parameters, outputSchema, render, execute, timeoutMs, concurrencySafe }) {
+  const parameterViolations = schemaViolations(parameters, `${name}.parameters`)
+  if (parameters?.type !== 'object') parameterViolations.push(`${name}.parameters must be an object schema`)
+  const outputViolations = schemaViolations(outputSchema, `${name}.output.schema`)
+  const violations = [...parameterViolations, ...outputViolations]
+  if (violations.length > 0) throw new Error(`defineTool(${name}): ${violations.join('; ')}`)
+  if (typeof render !== 'function') throw new Error(`defineTool(${name}): output.render is required`)
+  if (typeof execute !== 'function') throw new Error(`defineTool(${name}): execute is required`)
+
+  const definition = {
+    name,
+    description,
+    parameters,
+    output: {
+      schema: outputSchema,
+      render(args, value) {
+        return render(args, value)
+      },
+    },
+    async execute(args, exec) {
+      const argsViolations = valueViolations(parameters, args, '')
+      if (argsViolations.length > 0) {
+        const error = new Error(`invalid arguments: ${argsViolations.join('; ')}`)
+        error.name = 'ToolArgsError'
+        throw error
+      }
+      const raw = await execute(args ?? {}, exec)
+      // `undefined` is not a JSON value, but it is easy to produce: an optional
+      // field that simply is not there (`compare`, `error`, `measuredAt`) used to
+      // travel as an own property set to undefined, and the harness's snapshot
+      // then rejected the *whole* tool result with "value is not lossless JSON" —
+      // the model got no data at all and no way to tell why. Drop those keys
+      // first, then validate what is left.
+      const value = dropUndefined(raw)
+      const valueViolationsFound = valueViolations(outputSchema, value, '')
+      if (valueViolationsFound.length > 0) {
+        const error = new Error(`tool ${name} violated its declared output: ${valueViolationsFound.join('; ')}`)
+        error.name = 'ToolOutputError'
+        throw error
+      }
+      const nonLossless = findNonLossless(value, `${name}.output`)
+      if (nonLossless !== undefined) {
+        const error = new Error(`tool ${name} returned a value the harness cannot snapshot: ${nonLossless}`)
+        error.name = 'ToolOutputError'
+        throw error
+      }
+      return value
+    },
+  }
+  if (typeof timeoutMs === 'number') definition.timeoutMs = timeoutMs
+  definition.isConcurrencySafe = () => concurrencySafe === true
+  return definition
+}
+
+/**
+ * Render one JSON tool result as model-facing text, keeping it readable in a
+ * transcript rather than dumping raw JSON for every call.
+ *
+ * @param {any} value - canonical value.
+ * @param {number} [maxChars] - truncation budget.
+ * @returns {string} text.
+ */
+export function summarize(value, maxChars = 4000) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2)
+  return text.length <= maxChars ? text : `${text.slice(0, maxChars)}\n… (结果已截断，完整内容见工具卡片)`
+}