@purista/harness 1.0.0

package/dist/tools/mcp/schema.js

@@ -0,0 +1,251 @@
+import { ValidationError } from '../../errors/index.js';
+const supportedKeywords = new Set([
+    '$schema',
+    'additionalProperties',
+    'allOf',
+    'anyOf',
+    'const',
+    'enum',
+    'format',
+    'items',
+    'maximum',
+    'maxItems',
+    'maxLength',
+    'minimum',
+    'minItems',
+    'minLength',
+    'not',
+    'oneOf',
+    'pattern',
+    'properties',
+    'required',
+    'type'
+]);
+const supportedFormats = new Set(['uri', 'email', 'date-time', 'uuid']);
+const warned = new Set();
+export function validateMcpJsonSchema(opts) {
+    const schemaIssues = validateSchemaShape(opts.schema, '');
+    if (schemaIssues.length > 0) {
+        throw new ValidationError('MCP JSON Schema is malformed.', { where: opts.where, issues: schemaIssues });
+    }
+    warnUnsupportedKeywords(opts.toolId, opts.schema, '', opts.warn);
+    const issues = validateValue(opts.schema, opts.value, '');
+    if (issues.length > 0) {
+        throw new ValidationError('MCP JSON Schema validation failed.', { where: opts.where, issues });
+    }
+    if (!isJsonValue(opts.value)) {
+        throw new ValidationError('MCP value is not JSON serializable.', { where: opts.where, issues: [{ path: '', message: 'Value must be JSON serializable.' }] });
+    }
+    return opts.value;
+}
+export function assertMcpJsonSchema(toolId, schema, where, warn) {
+    const issues = validateSchemaShape(schema, '');
+    if (issues.length > 0)
+        throw new ValidationError('MCP JSON Schema is malformed.', { where, issues });
+    warnUnsupportedKeywords(toolId, schema, '', warn);
+}
+function validateSchemaShape(schema, pointer) {
+    if (!isRecord(schema))
+        return [{ path: pointer, message: 'Schema must be an object.' }];
+    const issues = [];
+    if ('type' in schema && !isValidType(schema.type))
+        issues.push({ path: pointerJoin(pointer, 'type'), message: 'Schema type must be a string or string array.', keyword: 'type' });
+    if ('properties' in schema && !isRecord(schema.properties))
+        issues.push({ path: pointerJoin(pointer, 'properties'), message: 'properties must be an object.', keyword: 'properties' });
+    if ('required' in schema && (!Array.isArray(schema.required) || !schema.required.every((value) => typeof value === 'string')))
+        issues.push({ path: pointerJoin(pointer, 'required'), message: 'required must be an array of strings.', keyword: 'required' });
+    if ('enum' in schema && !Array.isArray(schema.enum))
+        issues.push({ path: pointerJoin(pointer, 'enum'), message: 'enum must be an array.', keyword: 'enum' });
+    for (const key of ['oneOf', 'anyOf', 'allOf']) {
+        if (key in schema && (!Array.isArray(schema[key]) || !schema[key].every(isRecord)))
+            issues.push({ path: pointerJoin(pointer, key), message: `${key} must be an array of schemas.`, keyword: key });
+    }
+    for (const key of ['minimum', 'maximum', 'minLength', 'maxLength', 'minItems', 'maxItems']) {
+        if (key in schema && typeof schema[key] !== 'number')
+            issues.push({ path: pointerJoin(pointer, key), message: `${key} must be a number.`, keyword: key });
+    }
+    if ('pattern' in schema && typeof schema.pattern !== 'string')
+        issues.push({ path: pointerJoin(pointer, 'pattern'), message: 'pattern must be a string.', keyword: 'pattern' });
+    if ('format' in schema && typeof schema.format !== 'string')
+        issues.push({ path: pointerJoin(pointer, 'format'), message: 'format must be a string.', keyword: 'format' });
+    if ('additionalProperties' in schema && typeof schema.additionalProperties !== 'boolean' && !isRecord(schema.additionalProperties)) {
+        issues.push({ path: pointerJoin(pointer, 'additionalProperties'), message: 'additionalProperties must be a boolean or schema.', keyword: 'additionalProperties' });
+    }
+    if (isRecord(schema.properties)) {
+        for (const [name, child] of Object.entries(schema.properties))
+            issues.push(...validateSchemaShape(child, pointerJoin(pointerJoin(pointer, 'properties'), name)));
+    }
+    if (isRecord(schema.items))
+        issues.push(...validateSchemaShape(schema.items, pointerJoin(pointer, 'items')));
+    if (isRecord(schema.not))
+        issues.push(...validateSchemaShape(schema.not, pointerJoin(pointer, 'not')));
+    if (isRecord(schema.additionalProperties))
+        issues.push(...validateSchemaShape(schema.additionalProperties, pointerJoin(pointer, 'additionalProperties')));
+    for (const key of ['oneOf', 'anyOf', 'allOf']) {
+        if (Array.isArray(schema[key])) {
+            ;
+            schema[key].forEach((child, index) => {
+                issues.push(...validateSchemaShape(child, pointerJoin(pointerJoin(pointer, key), String(index))));
+            });
+        }
+    }
+    return issues;
+}
+function validateValue(schema, value, path) {
+    const issues = [];
+    if ('type' in schema && !matchesType(schema.type, value)) {
+        issues.push({ path, message: `Value must match type ${JSON.stringify(schema.type)}.`, keyword: 'type' });
+        return issues;
+    }
+    if ('const' in schema && !deepEqual(value, schema.const))
+        issues.push({ path, message: 'Value must equal const.', keyword: 'const' });
+    if (Array.isArray(schema.enum) && !schema.enum.some((item) => deepEqual(item, value)))
+        issues.push({ path, message: 'Value must match one enum value.', keyword: 'enum' });
+    if (Array.isArray(schema.allOf)) {
+        for (const child of schema.allOf)
+            issues.push(...validateValue(child, value, path));
+    }
+    if (Array.isArray(schema.anyOf) && !schema.anyOf.some((child) => validateValue(child, value, path).length === 0))
+        issues.push({ path, message: 'Value must match at least one anyOf schema.', keyword: 'anyOf' });
+    if (Array.isArray(schema.oneOf) && schema.oneOf.filter((child) => validateValue(child, value, path).length === 0).length !== 1)
+        issues.push({ path, message: 'Value must match exactly one oneOf schema.', keyword: 'oneOf' });
+    if (isRecord(schema.not) && validateValue(schema.not, value, path).length === 0)
+        issues.push({ path, message: 'Value must not match schema.', keyword: 'not' });
+    if (typeof value === 'number') {
+        if (typeof schema.minimum === 'number' && value < schema.minimum)
+            issues.push({ path, message: `Value must be >= minimum ${schema.minimum}.`, keyword: 'minimum' });
+        if (typeof schema.maximum === 'number' && value > schema.maximum)
+            issues.push({ path, message: `Value must be <= maximum ${schema.maximum}.`, keyword: 'maximum' });
+    }
+    if (typeof value === 'string') {
+        if (typeof schema.minLength === 'number' && value.length < schema.minLength)
+            issues.push({ path, message: `Value length must be >= minLength ${schema.minLength}.`, keyword: 'minLength' });
+        if (typeof schema.maxLength === 'number' && value.length > schema.maxLength)
+            issues.push({ path, message: `Value length must be <= maxLength ${schema.maxLength}.`, keyword: 'maxLength' });
+        if (typeof schema.pattern === 'string' && !(new RegExp(schema.pattern).test(value)))
+            issues.push({ path, message: 'Value must match pattern.', keyword: 'pattern' });
+        if (typeof schema.format === 'string' && supportedFormats.has(schema.format) && !matchesFormat(schema.format, value))
+            issues.push({ path, message: `Value must match ${schema.format} format.`, keyword: 'format' });
+    }
+    if (Array.isArray(value)) {
+        if (typeof schema.minItems === 'number' && value.length < schema.minItems)
+            issues.push({ path, message: `Array length must be >= minItems ${schema.minItems}.`, keyword: 'minItems' });
+        if (typeof schema.maxItems === 'number' && value.length > schema.maxItems)
+            issues.push({ path, message: `Array length must be <= maxItems ${schema.maxItems}.`, keyword: 'maxItems' });
+        if (isRecord(schema.items))
+            value.forEach((item, index) => issues.push(...validateValue(schema.items, item, pointerJoin(path, String(index)))));
+    }
+    if (isPlainObject(value))
+        validateObject(schema, value, path, issues);
+    return issues;
+}
+function validateObject(schema, value, path, issues) {
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    if (Array.isArray(schema.required)) {
+        for (const required of schema.required) {
+            if (!(required in value))
+                issues.push({ path: pointerJoin(path, required), message: 'Required property is missing.', keyword: 'required' });
+        }
+    }
+    for (const [name, child] of Object.entries(properties)) {
+        if (name in value)
+            issues.push(...validateValue(child, value[name], pointerJoin(path, name)));
+    }
+    for (const key of Object.keys(value)) {
+        if (key in properties)
+            continue;
+        if (schema.additionalProperties === false)
+            issues.push({ path: pointerJoin(path, key), message: 'Unknown property is not allowed.', keyword: 'additionalProperties' });
+        if (isRecord(schema.additionalProperties))
+            issues.push(...validateValue(schema.additionalProperties, value[key], pointerJoin(path, key)));
+    }
+}
+function warnUnsupportedKeywords(toolId, schema, pointer, warn) {
+    if (!isRecord(schema))
+        return;
+    for (const [key, value] of Object.entries(schema)) {
+        if (!supportedKeywords.has(key))
+            emitWarning(toolId, key, pointerJoin(pointer, key), warn);
+        if (key === 'format' && typeof value === 'string' && !supportedFormats.has(value))
+            emitWarning(toolId, `format:${value}`, pointerJoin(pointer, key), warn);
+    }
+    if (isRecord(schema.properties))
+        for (const [name, child] of Object.entries(schema.properties))
+            warnUnsupportedKeywords(toolId, child, pointerJoin(pointerJoin(pointer, 'properties'), name), warn);
+    if (isRecord(schema.items))
+        warnUnsupportedKeywords(toolId, schema.items, pointerJoin(pointer, 'items'), warn);
+    if (isRecord(schema.not))
+        warnUnsupportedKeywords(toolId, schema.not, pointerJoin(pointer, 'not'), warn);
+    if (isRecord(schema.additionalProperties))
+        warnUnsupportedKeywords(toolId, schema.additionalProperties, pointerJoin(pointer, 'additionalProperties'), warn);
+    for (const key of ['oneOf', 'anyOf', 'allOf']) {
+        if (Array.isArray(schema[key]))
+            schema[key].forEach((child, index) => warnUnsupportedKeywords(toolId, child, pointerJoin(pointerJoin(pointer, key), String(index)), warn));
+    }
+}
+function emitWarning(toolId, keyword, path, warn) {
+    const key = `${toolId}\0${keyword}\0${path}`;
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    warn?.({ toolId, keyword, path, message: `Unsupported MCP JSON Schema keyword ${keyword} at ${path}.` });
+}
+function isValidType(value) {
+    const valid = new Set(['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']);
+    return typeof value === 'string' ? valid.has(value) : Array.isArray(value) && value.every((item) => typeof item === 'string' && valid.has(item));
+}
+function matchesType(type, value) {
+    if (Array.isArray(type))
+        return type.some((item) => matchesType(item, value));
+    switch (type) {
+        case 'object': return isPlainObject(value);
+        case 'array': return Array.isArray(value);
+        case 'string': return typeof value === 'string';
+        case 'number': return typeof value === 'number' && Number.isFinite(value);
+        case 'integer': return Number.isInteger(value);
+        case 'boolean': return typeof value === 'boolean';
+        case 'null': return value === null;
+        default: return true;
+    }
+}
+function matchesFormat(format, value) {
+    if (format === 'email')
+        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+    if (format === 'uri') {
+        try {
+            new URL(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (format === 'date-time')
+        return !Number.isNaN(Date.parse(value));
+    if (format === 'uuid')
+        return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+    return true;
+}
+function pointerJoin(base, key) {
+    return `${base}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}`;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isPlainObject(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+function isJsonValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (isPlainObject(value))
+        return Object.values(value).every(isJsonValue);
+    return false;
+}
+function deepEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}

package/dist/tools/mcp/stdio.d.ts

@@ -0,0 +1,2 @@
+import type { McpTransportRunner, ResolvedMcpStdioTool } from './runner.js';
+export declare function createStdioMcpTransportRunner(config: ResolvedMcpStdioTool): McpTransportRunner;

package/dist/tools/mcp/stdio.js

@@ -0,0 +1,122 @@
+import { McpProtocolError, OperationTimeoutError, SandboxNoExecutorError } from '../../errors/index.js';
+import { withMcpTimeout } from './runner.js';
+const protocolVersion = '2025-06-18';
+export function createStdioMcpTransportRunner(config) {
+    let installPromise;
+    async function ensureInstalled(signal) {
+        if (!config.install)
+            return;
+        installPromise ??= runInstall(config, signal);
+        return installPromise;
+    }
+    return {
+        async listTools(options) {
+            return withMcpTimeout({ ...(options?.signal ? { signal: options.signal } : {}), timeoutMs: options?.timeoutMs ?? config.timeoutMs, scope: 'tool' }, async (signal) => {
+                await ensureInstalled(signal);
+                const result = await exchange(config, [{ id: 1, method: 'tools/list', params: {} }], signal, options?.timeoutMs);
+                return readResult(result, 1, 'list', (value) => {
+                    if (!isRecord(value) || !Array.isArray(value['tools']))
+                        return [];
+                    return value['tools'];
+                });
+            });
+        },
+        async callTool(name, input, options) {
+            return withMcpTimeout({ ...(options?.signal ? { signal: options.signal } : {}), timeoutMs: options?.timeoutMs ?? config.timeoutMs, scope: 'tool' }, async (signal) => {
+                await ensureInstalled(signal);
+                const result = await exchange(config, [{ id: 1, method: 'tools/call', params: { name, arguments: input } }], signal, options?.timeoutMs);
+                return readResult(result, 1, 'call', (value) => value);
+            });
+        },
+        async close() {
+            installPromise = undefined;
+        }
+    };
+}
+async function runInstall(config, signal) {
+    if (config.sandbox.executor !== 'available') {
+        throw new SandboxNoExecutorError('MCP stdio install requires a sandbox executor.', { session_id: 'unknown' });
+    }
+    const install = config.install;
+    if (!install)
+        return;
+    const result = await config.sandbox.exec(install.command, {
+        ...(install.cwd ? { cwd: install.cwd } : {}),
+        ...(install.env ? { env: install.env } : {}),
+        timeoutMs: install.timeoutMs ?? config.timeoutMs,
+        ...(signal ? { signal } : {})
+    });
+    if (result.exitCode !== 0) {
+        throw mapStdioError(config, 'connect', new Error(`MCP install failed with exit code ${result.exitCode}: ${result.stderr || result.stdout}`));
+    }
+}
+async function exchange(config, calls, signal, timeoutMs) {
+    if (config.sandbox.executor !== 'available') {
+        throw new SandboxNoExecutorError('MCP stdio requires a sandbox executor.', { session_id: 'unknown' });
+    }
+    const stdin = [
+        JSON.stringify({
+            jsonrpc: '2.0',
+            id: 0,
+            method: 'initialize',
+            params: {
+                protocolVersion,
+                capabilities: {},
+                clientInfo: { name: '@purista/harness', version: '0.0.0' }
+            }
+        }),
+        JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} }),
+        ...calls.map((call) => JSON.stringify({ jsonrpc: '2.0', id: call.id, method: call.method, params: call.params }))
+    ].join('\n') + '\n';
+    try {
+        const result = await config.sandbox.exec(commandLine(config.command, config.args), {
+            stdin,
+            ...(config.env ? { env: config.env } : {}),
+            timeoutMs: timeoutMs ?? config.timeoutMs,
+            ...(signal ? { signal } : {})
+        });
+        if (result.exitCode !== 0) {
+            throw new Error(`MCP server exited with code ${result.exitCode}: ${result.stderr || result.stdout}`);
+        }
+        return parseResponses(result.stdout);
+    }
+    catch (error) {
+        if (error instanceof OperationTimeoutError)
+            throw mapStdioError(config, calls[0]?.method === 'tools/list' ? 'list' : 'call', error);
+        throw mapStdioError(config, calls[0]?.method === 'tools/list' ? 'list' : 'call', error);
+    }
+}
+function readResult(responses, id, phase, map) {
+    const response = responses.find((candidate) => candidate.id === id);
+    if (!response)
+        throw new Error(`MCP ${phase} response missing.`);
+    if (response.error)
+        throw new Error(response.error.message ?? `MCP ${phase} failed.`);
+    return map(response.result);
+}
+function parseResponses(stdout) {
+    const responses = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{'))
+            continue;
+        const parsed = JSON.parse(trimmed);
+        if (isRecord(parsed) && ('id' in parsed || 'result' in parsed || 'error' in parsed))
+            responses.push(parsed);
+    }
+    return responses;
+}
+function commandLine(command, args) {
+    return [command, ...(args ?? [])].map(shellQuote).join(' ');
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:=@+-]+$/.test(value))
+        return value;
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function mapStdioError(config, phase, error) {
+    return new McpProtocolError('MCP stdio protocol failure.', { tool_id: config.localToolId, transport: 'stdio', phase }, error);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/ulid/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generates a monotonic ULID-like identifier.
+ *
+ * Subsequent calls within the same millisecond increment the random suffix to preserve ordering.
+ */
+export declare function ulid(): string;

package/dist/ulid/index.js

@@ -0,0 +1,35 @@
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+let lastTime = -1;
+let lastRandom = 0n;
+function encode(value, length) {
+    let out = '';
+    let input = value;
+    const base = 32n;
+    for (let i = 0; i < length; i += 1) {
+        const index = Number(input % base);
+        out = ENCODING[index] + out;
+        input /= base;
+    }
+    return out;
+}
+function nextRandom() {
+    const now = Date.now();
+    if (now !== lastTime) {
+        lastTime = now;
+        const seed = BigInt(Math.floor(Math.random() * 2 ** 24));
+        lastRandom = seed << 56n;
+        return lastRandom;
+    }
+    lastRandom += 1n;
+    return lastRandom;
+}
+/**
+ * Generates a monotonic ULID-like identifier.
+ *
+ * Subsequent calls within the same millisecond increment the random suffix to preserve ordering.
+ */
+export function ulid() {
+    const timePart = encode(BigInt(Date.now()), 10);
+    const randomPart = encode(nextRandom(), 16);
+    return `${timePart}${randomPart}`;
+}

package/dist/workflows/index.d.ts

@@ -0,0 +1,8 @@
+import type { BuilderState, InvokeOptions, WorkflowContext, WorkflowDefinition } from '../harness/defineHarness.js';
+export declare function runWorkflow<S extends BuilderState>(args: {
+    workflowId: string;
+    workflow: WorkflowDefinition<S, any, any>;
+    input: unknown;
+    ctx: Omit<WorkflowContext<S, unknown, unknown>, 'input'>;
+    opts?: InvokeOptions;
+}): Promise<unknown>;

package/dist/workflows/index.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { OperationCancelledError, ValidationError } from '../errors/index.js';
+export async function runWorkflow(args) {
+    if (args.ctx['signal'].aborted)
+        throw new OperationCancelledError('Workflow execution was cancelled.', { scope: 'workflow' });
+    const schema = args.workflow.input;
+    let parsed;
+    try {
+        parsed = schema ? schema.parse(args.input) : args.input;
+    }
+    catch (error) {
+        throw new ValidationError('Workflow input validation failed.', { where: 'workflow_input', issues: validationIssues(error) }, error);
+    }
+    const output = await args.workflow.handler({ ...args.ctx, input: parsed });
+    if (!args.workflow.output)
+        return output;
+    try {
+        return args.workflow.output.parse(output);
+    }
+    catch (error) {
+        throw new ValidationError('Workflow output validation failed.', { where: 'workflow_output', issues: validationIssues(error) }, error);
+    }
+}
+function validationIssues(error) {
+    return error instanceof z.ZodError ? JSON.parse(JSON.stringify(error.issues)) : error;
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@purista/harness",
+  "version": "1.0.0",
+  "description": "Self-hosted enterprise agent harness for typed tools, agents, workflows, state, sandboxing, and telemetry.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/puristajs/harness",
+    "directory": "packages/harness"
+  },
+  "bugs": {
+    "url": "https://github.com/puristajs/harness/issues"
+  },
+  "homepage": "https://github.com/puristajs/harness#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:types": "tsc -p tsconfig.type-tests.json",
+    "test": "vitest run",
+    "test:unit": "vitest run src",
+    "test:contracts": "vitest run src/ports test/sandbox.test.ts",
+    "test:integration": "vitest run test/harness.test.ts test/tools.test.ts test/skills.test.ts test/telemetry-flow.test.ts",
+    "test:failure": "vitest run test/failure"
+  },
+  "dependencies": {
+    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentelemetry/api": "^1.9.1",
+    "just-bash": "^2.14.4"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "just-bash": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentelemetry/context-async-hooks": "^2.7.1",
+    "@types/node": "^25.6.0",
+    "just-bash": "^2.14.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  }
+}