@finalai/agent-definition 0.1.0

package/dist/modules/runtime/schema-validation.mjs

@@ -0,0 +1,238 @@
+import {
+  jsonObjectSchema,
+  jsonValueSchema
+} from "@finalai/agent-provider";
+import { compileSchema, isSchemaNode } from "json-schema-library";
+import { remotes } from "json-schema-library/remotes";
+import * as z from "zod";
+import { callableSchema, fieldOf } from "./values.mjs";
+var SchemaIo = /* @__PURE__ */ ((SchemaIo2) => {
+  SchemaIo2["Input"] = "input";
+  SchemaIo2["Output"] = "output";
+  return SchemaIo2;
+})(SchemaIo || {});
+const dialects = /* @__PURE__ */ new Set([
+  "https://json-schema.org/draft/2020-12/schema",
+  "https://json-schema.org/draft/2019-09/schema",
+  "http://json-schema.org/draft-07/schema#",
+  "https://json-schema.org/draft-07/schema#",
+  "http://json-schema.org/draft-06/schema#",
+  "https://json-schema.org/draft-06/schema#",
+  "http://json-schema.org/draft-04/schema#",
+  "https://json-schema.org/draft-04/schema#"
+]);
+const vocabularies = /* @__PURE__ */ new Set([
+  "https://json-schema.org/draft/2020-12/vocab/core",
+  "https://json-schema.org/draft/2020-12/vocab/applicator",
+  "https://json-schema.org/draft/2020-12/vocab/validation",
+  "https://json-schema.org/draft/2020-12/vocab/unevaluated",
+  "https://json-schema.org/draft/2020-12/vocab/meta-data",
+  "https://json-schema.org/draft/2020-12/vocab/format-annotation",
+  "https://json-schema.org/draft/2020-12/vocab/format-assertion",
+  "https://json-schema.org/draft/2020-12/vocab/content",
+  "https://json-schema.org/draft/2019-09/vocab/core",
+  "https://json-schema.org/draft/2019-09/vocab/applicator",
+  "https://json-schema.org/draft/2019-09/vocab/validation",
+  "https://json-schema.org/draft/2019-09/vocab/meta-data",
+  "https://json-schema.org/draft/2019-09/vocab/format",
+  "https://json-schema.org/draft/2019-09/vocab/content"
+]);
+const declarationSchema = z.looseObject({
+  $schema: z.string().optional(),
+  $vocabulary: z.record(z.string(), z.boolean()).optional()
+});
+const checkDialect = (value) => {
+  if (z.boolean().safeParse(value).success) return;
+  const schema = declarationSchema.parse(value);
+  if (schema.$schema != null && !dialects.has(schema.$schema))
+    throw new Error(`Unsupported JSON Schema dialect ${schema.$schema}`);
+  for (const [name, required] of Object.entries(schema.$vocabulary ?? {})) {
+    if (required && !vocabularies.has(name))
+      throw new Error(`Unsupported required JSON Schema vocabulary ${name}`);
+  }
+};
+const dialectByVersion = {
+  "draft-04": "http://json-schema.org/draft-04/schema#",
+  "draft-06": "http://json-schema.org/draft-06/schema#",
+  "draft-07": "http://json-schema.org/draft-07/schema#",
+  "draft-2019-09": "https://json-schema.org/draft/2019-09/schema",
+  "draft-2020-12": "https://json-schema.org/draft/2020-12/schema"
+};
+let metaRoot = null;
+const metaSchemas = () => {
+  if (metaRoot != null) return metaRoot;
+  const schemas = z.array(jsonObjectSchema).parse(remotes).map((schema) => {
+    const identity = z.string().parse(schema.$id ?? schema.id).replace(/#$/, "");
+    const remote = { ...schema, $id: identity };
+    if (schema.id != null) remote["id"] = identity;
+    return remote;
+  });
+  metaRoot = compileSchema(
+    {},
+    { remotes: schemas, formatAssertion: true, throwOnInvalidRef: true }
+  );
+  return metaRoot;
+};
+const schemaKeywords = /* @__PURE__ */ new Set([
+  "additionalItems",
+  "additionalProperties",
+  "contains",
+  "propertyNames",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+  "not",
+  "if",
+  "then",
+  "else"
+]);
+const schemaMaps = /* @__PURE__ */ new Set([
+  "properties",
+  "patternProperties",
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "dependencies"
+]);
+const schemaArrays = /* @__PURE__ */ new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+const childPlaceholder = (value) => jsonObjectSchema.safeParse(value).success ? {} : value;
+const shallowDeclaration = (schema) => Object.fromEntries(
+  Object.entries(schema).map(([key, value]) => {
+    if (schemaKeywords.has(key)) return [key, childPlaceholder(value)];
+    if ((schemaArrays.has(key) || key === "items") && Array.isArray(value))
+      return [key, value.map(childPlaceholder)];
+    if (key === "items") return [key, childPlaceholder(value)];
+    const object = jsonObjectSchema.safeParse(value);
+    if (schemaMaps.has(key) && object.success)
+      return [
+        key,
+        Object.fromEntries(
+          Object.entries(object.data).map(([name, child]) => [name, childPlaceholder(child)])
+        )
+      ];
+    return [key, value];
+  })
+);
+const checkDeclaration = (node) => {
+  if (z.boolean().safeParse(node.schema).success) return;
+  const schema = jsonObjectSchema.parse(node.schema);
+  checkDialect(schema);
+  const dialect = Object.entries(dialectByVersion).find(
+    ([version]) => version === node.context.version
+  )?.[1];
+  if (dialect == null) throw new Error(`Unsupported JSON Schema version ${node.context.version}`);
+  const meta = metaSchemas().getNodeRef(dialect);
+  if (!isSchemaNode(meta)) throw new Error(`Missing JSON Schema metaschema ${dialect}`);
+  const result = meta.validate(shallowDeclaration(schema));
+  if (!result.valid) throw new Error(result.errors.map((issue) => issue.message).join("; "));
+};
+const canonicalJson = (value) => {
+  if (Array.isArray(value)) return value.map(canonicalJson);
+  const object = jsonObjectSchema.safeParse(value);
+  if (!object.success) return value;
+  return Object.fromEntries(
+    Object.entries(object.data).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, canonicalJson(item)])
+  );
+};
+const validatorFor = (schema) => {
+  const text = JSON.stringify(schema);
+  if (text == null) throw new Error("Expected a JSON Schema object");
+  const parsed = jsonObjectSchema.parse(canonicalJson(jsonObjectSchema.parse(JSON.parse(text))));
+  checkDialect(parsed);
+  const node = compileSchema(parsed, { formatAssertion: true, throwOnInvalidRef: true });
+  if (node.schemaErrors != null && node.schemaErrors.length > 0)
+    throw new Error(node.schemaErrors.map((issue) => issue.message).join("; "));
+  const nodes = /* @__PURE__ */ new Set([node, ...Object.values(node.context.refs)]);
+  for (const child of nodes) {
+    checkDeclaration(child);
+    const ref = fieldOf(child.schema, "$ref") ?? fieldOf(child.schema, "$dynamicRef") ?? fieldOf(child.schema, "$recursiveRef");
+    if (ref == null) continue;
+    const resolved = child.resolveRef();
+    if (!isSchemaNode(resolved))
+      throw new Error(`Unresolved JSON Schema reference ${String(ref)} at ${child.schemaLocation}`);
+  }
+  return node;
+};
+const jsonSchemaError = (schema, value) => {
+  const validator = validatorFor(schema);
+  const parsed = jsonValueSchema.safeParse(value);
+  if (!parsed.success) return "Expected a JSON-compatible value";
+  const result = validator.validate(canonicalJson(parsed.data));
+  return result.valid ? null : result.errors.map((issue) => issue.message).join("; ");
+};
+const jsonSchemaDeclarationError = (schema) => {
+  try {
+    validatorFor(schema);
+    return null;
+  } catch (cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+  }
+};
+const standardValidatorSchema = z.looseObject({
+  "~standard": z.looseObject({
+    version: z.literal(1),
+    vendor: z.string(),
+    validate: callableSchema
+  })
+});
+const validationResultSchema = z.looseObject({
+  value: z.unknown().optional(),
+  issues: z.array(z.looseObject({ message: z.string().optional() })).optional()
+});
+const validateSchemaValue = async (args) => {
+  if (args.schema == null) return args.value;
+  const standard = standardValidatorSchema.safeParse(args.schema);
+  if (standard.success) {
+    if (standard.data["~standard"].vendor === "zod") {
+      const parser = callableSchema.safeParse(fieldOf(args.schema, "safeParseAsync"));
+      if (parser.success) {
+        const result2 = z.looseObject({
+          success: z.boolean(),
+          data: z.unknown().optional(),
+          error: z.looseObject({ issues: z.array(z.object({ message: z.string() })) }).optional()
+        }).parse(await parser.data.call(args.schema, args.value));
+        if (!result2.success)
+          throw new Error(
+            `Invalid ${args.what}: ${result2.error?.issues.map((issue) => issue.message).join("; ") ?? "invalid"}`
+          );
+        return result2.data;
+      }
+    }
+    const raw = await standard.data["~standard"].validate.call(
+      fieldOf(args.schema, "~standard"),
+      args.value
+    );
+    const result = validationResultSchema.parse(raw);
+    if (result.issues != null)
+      throw new Error(
+        `Invalid ${args.what}: ${result.issues.map((issue) => issue.message ?? "invalid").join("; ") || "invalid"}`
+      );
+    if (!Object.hasOwn(result, "value"))
+      throw new Error(`Invalid ${args.what}: schema validator returned no value`);
+    return result.value;
+  }
+  const error = jsonSchemaError(args.schema, args.value);
+  if (error != null) throw new Error(`Invalid ${args.what}: ${error}`);
+  return args.value;
+};
+const resultMatchesSchema = (schema, value) => {
+  if (schema == null) return true;
+  try {
+    const standard = standardValidatorSchema.safeParse(schema);
+    if (!standard.success) return jsonSchemaError(schema, value) == null;
+    const jsonSchemas = fieldOf(fieldOf(schema, "~standard"), "jsonSchema");
+    const converter = callableSchema.safeParse(fieldOf(jsonSchemas, "output" /* Output */));
+    if (!converter.success) return false;
+    return jsonSchemaError(converter.data.call(jsonSchemas, { target: "draft-2020-12" }), value) == null;
+  } catch {
+    return false;
+  }
+};
+export {
+  SchemaIo,
+  jsonSchemaDeclarationError,
+  jsonSchemaError,
+  resultMatchesSchema,
+  standardValidatorSchema,
+  validateSchemaValue
+};
+//# sourceMappingURL=schema-validation.mjs.map

package/dist/modules/runtime/schema-validation.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/runtime/schema-validation.ts"],
+  "sourcesContent": ["import {\n  jsonObjectSchema,\n  jsonValueSchema,\n  type JsonObject,\n  type JsonValue,\n} from '@finalai/agent-provider';\nimport { compileSchema, isSchemaNode, type SchemaNode } from 'json-schema-library';\nimport { remotes } from 'json-schema-library/remotes';\nimport * as z from 'zod';\nimport { callableSchema, fieldOf, type AuthoredValue } from \"./values.mjs\";\n\nexport enum SchemaIo {\n  Input = 'input',\n  Output = 'output',\n}\n\nconst dialects = new Set([\n  'https://json-schema.org/draft/2020-12/schema',\n  'https://json-schema.org/draft/2019-09/schema',\n  'http://json-schema.org/draft-07/schema#',\n  'https://json-schema.org/draft-07/schema#',\n  'http://json-schema.org/draft-06/schema#',\n  'https://json-schema.org/draft-06/schema#',\n  'http://json-schema.org/draft-04/schema#',\n  'https://json-schema.org/draft-04/schema#',\n]);\nconst vocabularies = new Set([\n  'https://json-schema.org/draft/2020-12/vocab/core',\n  'https://json-schema.org/draft/2020-12/vocab/applicator',\n  'https://json-schema.org/draft/2020-12/vocab/validation',\n  'https://json-schema.org/draft/2020-12/vocab/unevaluated',\n  'https://json-schema.org/draft/2020-12/vocab/meta-data',\n  'https://json-schema.org/draft/2020-12/vocab/format-annotation',\n  'https://json-schema.org/draft/2020-12/vocab/format-assertion',\n  'https://json-schema.org/draft/2020-12/vocab/content',\n  'https://json-schema.org/draft/2019-09/vocab/core',\n  'https://json-schema.org/draft/2019-09/vocab/applicator',\n  'https://json-schema.org/draft/2019-09/vocab/validation',\n  'https://json-schema.org/draft/2019-09/vocab/meta-data',\n  'https://json-schema.org/draft/2019-09/vocab/format',\n  'https://json-schema.org/draft/2019-09/vocab/content',\n]);\nconst declarationSchema = z.looseObject({\n  $schema: z.string().optional(),\n  $vocabulary: z.record(z.string(), z.boolean()).optional(),\n});\n\nconst checkDialect = (value: AuthoredValue): void => {\n  if (z.boolean().safeParse(value).success) return;\n  const schema = declarationSchema.parse(value);\n  if (schema.$schema != null && !dialects.has(schema.$schema))\n    throw new Error(`Unsupported JSON Schema dialect ${schema.$schema}`);\n  for (const [name, required] of Object.entries(schema.$vocabulary ?? {})) {\n    if (required && !vocabularies.has(name))\n      throw new Error(`Unsupported required JSON Schema vocabulary ${name}`);\n  }\n};\n\nconst dialectByVersion = {\n  'draft-04': 'http://json-schema.org/draft-04/schema#',\n  'draft-06': 'http://json-schema.org/draft-06/schema#',\n  'draft-07': 'http://json-schema.org/draft-07/schema#',\n  'draft-2019-09': 'https://json-schema.org/draft/2019-09/schema',\n  'draft-2020-12': 'https://json-schema.org/draft/2020-12/schema',\n} satisfies Record<string, string>;\nlet metaRoot: SchemaNode | null = null;\nconst metaSchemas = (): SchemaNode => {\n  if (metaRoot != null) return metaRoot;\n  const schemas = z\n    .array(jsonObjectSchema)\n    .parse(remotes)\n    .map((schema) => {\n      const identity = z\n        .string()\n        .parse(schema.$id ?? schema.id)\n        .replace(/#$/, '');\n      const remote: JsonObject = { ...schema, $id: identity };\n      if (schema.id != null) remote['id'] = identity;\n      return remote;\n    });\n  metaRoot = compileSchema(\n    {},\n    { remotes: schemas, formatAssertion: true, throwOnInvalidRef: true },\n  );\n  return metaRoot;\n};\n\nconst schemaKeywords = new Set([\n  'additionalItems',\n  'additionalProperties',\n  'contains',\n  'propertyNames',\n  'unevaluatedItems',\n  'unevaluatedProperties',\n  'not',\n  'if',\n  'then',\n  'else',\n]);\nconst schemaMaps = new Set([\n  'properties',\n  'patternProperties',\n  '$defs',\n  'definitions',\n  'dependentSchemas',\n  'dependencies',\n]);\nconst schemaArrays = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);\nconst childPlaceholder = (value: JsonValue): JsonValue =>\n  jsonObjectSchema.safeParse(value).success ? {} : value;\n\n// Validate each parsed node against its own dialect. Child schemas are checked\n// separately, so an embedded resource can declare a different dialect.\nconst shallowDeclaration = (schema: JsonObject): JsonObject =>\n  Object.fromEntries(\n    Object.entries(schema).map(([key, value]) => {\n      if (schemaKeywords.has(key)) return [key, childPlaceholder(value)];\n      if ((schemaArrays.has(key) || key === 'items') && Array.isArray(value))\n        return [key, value.map(childPlaceholder)];\n      if (key === 'items') return [key, childPlaceholder(value)];\n      const object = jsonObjectSchema.safeParse(value);\n      if (schemaMaps.has(key) && object.success)\n        return [\n          key,\n          Object.fromEntries(\n            Object.entries(object.data).map(([name, child]) => [name, childPlaceholder(child)]),\n          ),\n        ];\n      return [key, value];\n    }),\n  );\nconst checkDeclaration = (node: SchemaNode): void => {\n  if (z.boolean().safeParse(node.schema).success) return;\n  const schema = jsonObjectSchema.parse(node.schema);\n  checkDialect(schema);\n  const dialect = Object.entries(dialectByVersion).find(\n    ([version]) => version === node.context.version,\n  )?.[1];\n  if (dialect == null) throw new Error(`Unsupported JSON Schema version ${node.context.version}`);\n  const meta = metaSchemas().getNodeRef(dialect);\n  if (!isSchemaNode(meta)) throw new Error(`Missing JSON Schema metaschema ${dialect}`);\n  const result = meta.validate(shallowDeclaration(schema));\n  if (!result.valid) throw new Error(result.errors.map((issue) => issue.message).join('; '));\n};\n\nconst canonicalJson = (value: JsonValue): JsonValue => {\n  if (Array.isArray(value)) return value.map(canonicalJson);\n  const object = jsonObjectSchema.safeParse(value);\n  if (!object.success) return value;\n  return Object.fromEntries(\n    Object.entries(object.data)\n      .sort(([left], [right]) => left.localeCompare(right))\n      .map(([key, item]) => [key, canonicalJson(item)]),\n  );\n};\n\n// Compile a private tree for each validation. The interpreter never fetches\n// references or shares a schema registry, and retains no tool data between calls.\nconst validatorFor = (schema: AuthoredValue): SchemaNode => {\n  const text = JSON.stringify(schema);\n  if (text == null) throw new Error('Expected a JSON Schema object');\n  const parsed = jsonObjectSchema.parse(canonicalJson(jsonObjectSchema.parse(JSON.parse(text))));\n  checkDialect(parsed);\n  const node = compileSchema(parsed, { formatAssertion: true, throwOnInvalidRef: true });\n  if (node.schemaErrors != null && node.schemaErrors.length > 0)\n    throw new Error(node.schemaErrors.map((issue) => issue.message).join('; '));\n  // Check even unused declarations: an unresolved reference must fail publish,\n  // rather than surviving until some input happens to select that branch.\n  const nodes = new Set([node, ...Object.values(node.context.refs)]);\n  for (const child of nodes) {\n    checkDeclaration(child);\n    const ref =\n      fieldOf(child.schema, '$ref') ??\n      fieldOf(child.schema, '$dynamicRef') ??\n      fieldOf(child.schema, '$recursiveRef');\n    if (ref == null) continue;\n    const resolved = child.resolveRef();\n    if (!isSchemaNode(resolved))\n      throw new Error(`Unresolved JSON Schema reference ${String(ref)} at ${child.schemaLocation}`);\n  }\n  return node;\n};\n\nexport const jsonSchemaError = (schema: AuthoredValue, value: AuthoredValue): string | null => {\n  const validator = validatorFor(schema);\n  const parsed = jsonValueSchema.safeParse(value);\n  if (!parsed.success) return 'Expected a JSON-compatible value';\n  // JSON object order is immaterial, including inside enum assertions.\n  const result = validator.validate(canonicalJson(parsed.data));\n  return result.valid ? null : result.errors.map((issue) => issue.message).join('; ');\n};\n\nexport const jsonSchemaDeclarationError = (schema: AuthoredValue): string | null => {\n  try {\n    validatorFor(schema);\n    return null;\n  } catch (cause) {\n    return cause instanceof Error ? cause.message : String(cause);\n  }\n};\n\nexport const standardValidatorSchema = z.looseObject({\n  '~standard': z.looseObject({\n    version: z.literal(1),\n    vendor: z.string(),\n    validate: callableSchema,\n  }),\n});\nconst validationResultSchema = z.looseObject({\n  value: z.unknown().optional(),\n  issues: z.array(z.looseObject({ message: z.string().optional() })).optional(),\n});\n\nexport const validateSchemaValue = async (args: {\n  schema: AuthoredValue;\n  value: AuthoredValue;\n  what: string;\n}): Promise<AuthoredValue> => {\n  if (args.schema == null) return args.value;\n  const standard = standardValidatorSchema.safeParse(args.schema);\n  if (standard.success) {\n    // Zod's Standard Schema validator retries asynchronous transforms after a\n    // synchronous attempt; its public async parser performs them only once.\n    if (standard.data['~standard'].vendor === 'zod') {\n      const parser = callableSchema.safeParse(fieldOf(args.schema, 'safeParseAsync'));\n      if (parser.success) {\n        const result = z\n          .looseObject({\n            success: z.boolean(),\n            data: z.unknown().optional(),\n            error: z.looseObject({ issues: z.array(z.object({ message: z.string() })) }).optional(),\n          })\n          .parse(await parser.data.call(args.schema, args.value));\n        if (!result.success)\n          throw new Error(\n            `Invalid ${args.what}: ${result.error?.issues.map((issue) => issue.message).join('; ') ?? 'invalid'}`,\n          );\n        return result.data;\n      }\n    }\n    const raw = await standard.data['~standard'].validate.call(\n      fieldOf(args.schema, '~standard'),\n      args.value,\n    );\n    const result = validationResultSchema.parse(raw);\n    if (result.issues != null)\n      throw new Error(\n        `Invalid ${args.what}: ${result.issues.map((issue) => issue.message ?? 'invalid').join('; ') || 'invalid'}`,\n      );\n    if (!Object.hasOwn(result, 'value'))\n      throw new Error(`Invalid ${args.what}: schema validator returned no value`);\n    return result.value;\n  }\n  const error = jsonSchemaError(args.schema, args.value);\n  if (error != null) throw new Error(`Invalid ${args.what}: ${error}`);\n  return args.value;\n};\n\n// Published results have already been transformed. Never run their input\n// validator again: use the output JSON Schema for synchronous hook narrowing.\nexport const resultMatchesSchema = (schema: AuthoredValue, value: AuthoredValue): boolean => {\n  if (schema == null) return true;\n  try {\n    const standard = standardValidatorSchema.safeParse(schema);\n    if (!standard.success) return jsonSchemaError(schema, value) == null;\n    const jsonSchemas = fieldOf(fieldOf(schema, '~standard'), 'jsonSchema');\n    const converter = callableSchema.safeParse(fieldOf(jsonSchemas, SchemaIo.Output));\n    if (!converter.success) return false;\n    return (\n      jsonSchemaError(converter.data.call(jsonSchemas, { target: 'draft-2020-12' }), value) == null\n    );\n  } catch {\n    return false;\n  }\n};\n"],
+  "mappings": "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",
+  "names": ["SchemaIo", "result"]
+}

package/dist/modules/runtime/values.d.mts

@@ -0,0 +1,20 @@
+import * as z from 'zod';
+export declare const authoredValueSchema: z.ZodUnknown;
+export type AuthoredValue = z.output<typeof authoredValueSchema>;
+export declare const optionalValueSchema: z.ZodOptional<z.ZodUnknown>;
+export type AuthoredCallable = (...args: AuthoredValue[]) => AuthoredValue;
+export declare const callableSchema: z.ZodCustom<AuthoredCallable, AuthoredCallable>;
+export declare const authoredRecordSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type AuthoredRecord = z.output<typeof authoredRecordSchema>;
+export declare const isCallable: (value: AuthoredValue) => value is AuthoredCallable;
+export declare const isString: (value: AuthoredValue) => value is string;
+export declare const isNumber: (value: AuthoredValue) => value is number;
+export declare const isBoolean: (value: AuthoredValue) => value is boolean;
+export declare const stringOrNull: (value: AuthoredValue) => string | null;
+export declare const isObjectLike: (value: AuthoredValue) => value is object;
+export declare const isPlainObject: (value: AuthoredValue) => value is AuthoredRecord;
+export declare const fieldOf: (value: AuthoredValue, key: string) => AuthoredValue;
+export declare const entriesOf: (value: AuthoredValue) => [string, AuthoredValue][];
+export declare const isPromiseLike: (value: AuthoredValue) => value is PromiseLike<AuthoredValue>;
+export declare const isAsyncIterable: (value: AuthoredValue) => value is AsyncIterable<AuthoredValue>;
+export declare const messageOf: (cause: unknown) => string;

package/dist/modules/runtime/values.mjs

@@ -0,0 +1,48 @@
+import * as z from "zod";
+const authoredValueSchema = z.unknown();
+const optionalValueSchema = authoredValueSchema.optional();
+const functionSchema = z.function();
+const callableSchema = z.custom(
+  (value) => functionSchema.safeParse(value).success
+);
+const authoredRecordSchema = z.record(z.string(), authoredValueSchema);
+const isCallable = (value) => callableSchema.safeParse(value).success;
+const isString = (value) => z.string().safeParse(value).success;
+const isNumber = (value) => z.number().safeParse(value).success;
+const isBoolean = (value) => z.boolean().safeParse(value).success;
+const stringOrNull = (value) => isString(value) ? value : null;
+const isObjectLike = (value) => value instanceof Object;
+const isPlainObject = (value) => {
+  if (!isObjectLike(value) || Array.isArray(value) || isCallable(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto == null || Object.getPrototypeOf(proto) == null;
+};
+const fieldOf = (value, key) => {
+  if (!isObjectLike(value) || !(key in value)) return void 0;
+  const parsed = z.looseObject({ [key]: optionalValueSchema }).safeParse(value);
+  if (parsed.success) return parsed.data[key];
+  return Object.getOwnPropertyDescriptor(value, key)?.value;
+};
+const entriesOf = (value) => isObjectLike(value) ? Object.entries(value) : [];
+const isPromiseLike = (value) => isCallable(fieldOf(value, "then"));
+const isAsyncIterable = (value) => isObjectLike(value) && Symbol.asyncIterator in value;
+const messageOf = (cause) => cause instanceof Error ? cause.message : String(cause);
+export {
+  authoredRecordSchema,
+  authoredValueSchema,
+  callableSchema,
+  entriesOf,
+  fieldOf,
+  isAsyncIterable,
+  isBoolean,
+  isCallable,
+  isNumber,
+  isObjectLike,
+  isPlainObject,
+  isPromiseLike,
+  isString,
+  messageOf,
+  optionalValueSchema,
+  stringOrNull
+};
+//# sourceMappingURL=values.mjs.map

package/dist/modules/runtime/values.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/runtime/values.ts"],
+  "sourcesContent": ["import * as z from 'zod';\n\n// Authored modules hand the compiler and the isolate arbitrary values; these\n// schemas decode them at that boundary. Each slot then parses the decoded\n// value with the schema of what it must be (a tool, a connection, ...).\n\n// A value produced by authored code, before its slot's schema has parsed it.\nexport const authoredValueSchema = z.unknown();\nexport type AuthoredValue = z.output<typeof authoredValueSchema>;\n\n// An object field that may be absent.\nexport const optionalValueSchema = authoredValueSchema.optional();\n\nexport type AuthoredCallable = (...args: AuthoredValue[]) => AuthoredValue;\n\n// zod's function check, not instanceof, so functions from another realm (the\n// local dev isolate's) are callable too.\nconst functionSchema = z.function();\nexport const callableSchema = z.custom<AuthoredCallable>(\n  (value) => functionSchema.safeParse(value).success,\n);\n\nexport const authoredRecordSchema = z.record(z.string(), authoredValueSchema);\nexport type AuthoredRecord = z.output<typeof authoredRecordSchema>;\n\nexport const isCallable = (value: AuthoredValue): value is AuthoredCallable =>\n  callableSchema.safeParse(value).success;\n\nexport const isString = (value: AuthoredValue): value is string =>\n  z.string().safeParse(value).success;\n\nexport const isNumber = (value: AuthoredValue): value is number =>\n  z.number().safeParse(value).success;\n\nexport const isBoolean = (value: AuthoredValue): value is boolean =>\n  z.boolean().safeParse(value).success;\n\nexport const stringOrNull = (value: AuthoredValue): string | null =>\n  isString(value) ? value : null;\n\n// Objects and functions (which may carry properties, like a defined harness).\nexport const isObjectLike = (value: AuthoredValue): value is object => value instanceof Object;\n\n// A plain object literal (from any realm): Object.prototype or null prototype.\nexport const isPlainObject = (value: AuthoredValue): value is AuthoredRecord => {\n  if (!isObjectLike(value) || Array.isArray(value) || isCallable(value)) return false;\n  const proto: AuthoredValue = Object.getPrototypeOf(value);\n  // Object.prototype itself is not `instanceof Object`; its own prototype is null.\n  return proto == null || Object.getPrototypeOf(proto) == null;\n};\n\n// Reads one named property of an authored object or function, including\n// getters and inherited properties.\nexport const fieldOf = (value: AuthoredValue, key: string): AuthoredValue => {\n  if (!isObjectLike(value) || !(key in value)) return undefined;\n  const parsed = z.looseObject({ [key]: optionalValueSchema }).safeParse(value);\n  if (parsed.success) return parsed.data[key];\n  return Object.getOwnPropertyDescriptor(value, key)?.value;\n};\n\n// Own enumerable entries of an authored object or function.\nexport const entriesOf = (value: AuthoredValue): [string, AuthoredValue][] =>\n  isObjectLike(value) ? Object.entries(value) : [];\n\nexport const isPromiseLike = (value: AuthoredValue): value is PromiseLike<AuthoredValue> =>\n  isCallable(fieldOf(value, 'then'));\n\nexport const isAsyncIterable = (value: AuthoredValue): value is AsyncIterable<AuthoredValue> =>\n  isObjectLike(value) && Symbol.asyncIterator in value;\n\nexport const messageOf = (cause: unknown): string =>\n  cause instanceof Error ? cause.message : String(cause);\n"],
+  "mappings": "AAAA,YAAY,OAAO;AAOZ,MAAM,sBAAsB,EAAE,QAAQ;AAItC,MAAM,sBAAsB,oBAAoB,SAAS;AAMhE,MAAM,iBAAiB,EAAE,SAAS;AAC3B,MAAM,iBAAiB,EAAE;AAAA,EAC9B,CAAC,UAAU,eAAe,UAAU,KAAK,EAAE;AAC7C;AAEO,MAAM,uBAAuB,EAAE,OAAO,EAAE,OAAO,GAAG,mBAAmB;AAGrE,MAAM,aAAa,CAAC,UACzB,eAAe,UAAU,KAAK,EAAE;AAE3B,MAAM,WAAW,CAAC,UACvB,EAAE,OAAO,EAAE,UAAU,KAAK,EAAE;AAEvB,MAAM,WAAW,CAAC,UACvB,EAAE,OAAO,EAAE,UAAU,KAAK,EAAE;AAEvB,MAAM,YAAY,CAAC,UACxB,EAAE,QAAQ,EAAE,UAAU,KAAK,EAAE;AAExB,MAAM,eAAe,CAAC,UAC3B,SAAS,KAAK,IAAI,QAAQ;AAGrB,MAAM,eAAe,CAAC,UAA0C,iBAAiB;AAGjF,MAAM,gBAAgB,CAAC,UAAkD;AAC9E,MAAI,CAAC,aAAa,KAAK,KAAK,MAAM,QAAQ,KAAK,KAAK,WAAW,KAAK,EAAG,QAAO;AAC9E,QAAM,QAAuB,OAAO,eAAe,KAAK;AAExD,SAAO,SAAS,QAAQ,OAAO,eAAe,KAAK,KAAK;AAC1D;AAIO,MAAM,UAAU,CAAC,OAAsB,QAA+B;AAC3E,MAAI,CAAC,aAAa,KAAK,KAAK,EAAE,OAAO,OAAQ,QAAO;AACpD,QAAM,SAAS,EAAE,YAAY,EAAE,CAAC,GAAG,GAAG,oBAAoB,CAAC,EAAE,UAAU,KAAK;AAC5E,MAAI,OAAO,QAAS,QAAO,OAAO,KAAK,GAAG;AAC1C,SAAO,OAAO,yBAAyB,OAAO,GAAG,GAAG;AACtD;AAGO,MAAM,YAAY,CAAC,UACxB,aAAa,KAAK,IAAI,OAAO,QAAQ,KAAK,IAAI,CAAC;AAE1C,MAAM,gBAAgB,CAAC,UAC5B,WAAW,QAAQ,OAAO,MAAM,CAAC;AAE5B,MAAM,kBAAkB,CAAC,UAC9B,aAAa,KAAK,KAAK,OAAO,iBAAiB;AAE1C,MAAM,YAAY,CAAC,UACxB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;",
+  "names": []
+}

package/fixtures/acme-fleet/agent/agent.ts

@@ -0,0 +1,74 @@
+import {
+  credentials,
+  defineAgent,
+  defineHarness,
+  type CredentialPolicyIface,
+} from '@finalai/agents';
+
+// Custom harness configuration is a type argument. Resume returns an endpoint,
+// and the API key secret read through a computed name is declared in `secrets`.
+const acmeFleet = defineHarness<{
+  region?: string;
+  apiKeySecret: string;
+  credentials: CredentialPolicyIface;
+}>({
+  describe: async () => ({
+    configSchema: {
+      type: 'object',
+      properties: {
+        credentials: { $ref: 'final://schemas/credential-policy' },
+        region: { type: 'string' },
+        apiKeySecret: { type: 'string' },
+      },
+      required: ['apiKeySecret', 'credentials'],
+    },
+    acp: { transports: ['ws'], mcp: ['http'] },
+    supports: { observe: false, resumeReplay: true, fork: false },
+  }),
+  open: async ({ sessionId, config, secrets }) => {
+    // Acme's fleet: ask it to start a Claude Code container in the chosen region and hand back an ACP WebSocket
+    const res = await fetch('https://fleet.acme.dev/sessions', {
+      method: 'POST',
+      headers: { authorization: `Bearer ${await secrets.get(config.apiKeySecret)}` },
+      body: JSON.stringify({
+        region: config.region,
+        program: 'claude-code',
+        externalId: sessionId,
+      }),
+    });
+    const { id, wsUrl, token } = await res.json();
+    return {
+      ref: { harnessSessionRef: id, generation: 1 },
+      transport: 'ws',
+      url: wsUrl,
+      headers: { authorization: `Bearer ${token}` },
+    };
+  },
+  resume: async ({ ref, config, secrets }) => {
+    const res = await fetch(`https://fleet.acme.dev/sessions/${ref.harnessSessionRef}/resume`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${await secrets.get(config.apiKeySecret)}` },
+    });
+    const { wsUrl, token } = await res.json();
+    return { ref, transport: 'ws', url: wsUrl, headers: { authorization: `Bearer ${token}` } };
+  },
+  park: async ({ ref }) => {
+    await fetch(`https://fleet.acme.dev/sessions/${ref.harnessSessionRef}/pause`, {
+      method: 'POST',
+    });
+  },
+  close: async ({ ref }) => {
+    await fetch(`https://fleet.acme.dev/sessions/${ref.harnessSessionRef}`, { method: 'DELETE' });
+  },
+  health: async () => ({ ok: true }),
+});
+
+export default defineAgent({
+  name: 'Release Scout',
+  secrets: ['acme-fleet-key'],
+  harness: acmeFleet({
+    credentials: credentials.chain({ payer: 'agent-owner', tryInOrder: [credentials.harness()] }),
+    region: 'eu',
+    apiKeySecret: 'acme-fleet-key',
+  }),
+});

package/fixtures/acme-fleet/agent/instructions.md

@@ -0,0 +1 @@
+You are Release Scout for the Final engineering team. Be brief. Cite release tags.

package/fixtures/assistant/agent/agent.ts

@@ -0,0 +1,16 @@
+import { defineAgent, credentials as definitionCredentials } from '@finalai/agents';
+import { serverlessPi } from '@finalai/final-agent-provider/harnesses';
+
+export default defineAgent({
+  harness: serverlessPi({
+    credentials: definitionCredentials.chain({
+      payer: 'organization',
+      tryInOrder: [
+        definitionCredentials.subscription({ owner: 'organization' }),
+        definitionCredentials.platform(),
+      ],
+    }),
+    model: 'gpt-6-sol',
+    reasoning: 'low',
+  }),
+});

package/fixtures/assistant/agent/instructions.md

@@ -0,0 +1 @@
+Help the user with their requests.

package/fixtures/assistant/agent/tools/current_time.ts

@@ -0,0 +1,9 @@
+import { defineTool } from '@finalai/agents';
+import * as z from 'zod';
+
+export default defineTool({
+  description: 'Read the current UTC time from the execution environment.',
+  inputSchema: z.strictObject({}),
+  outputSchema: z.object({ utc: z.string() }),
+  execute: () => ({ utc: new Date().toISOString() }),
+});

package/fixtures/assistant-with-tools/agent/agent.ts

@@ -0,0 +1,16 @@
+import { defineAgent, credentials as definitionCredentials } from '@finalai/agents';
+import { serverlessPi } from '@finalai/final-agent-provider/harnesses';
+
+export default defineAgent({
+  harness: serverlessPi({
+    credentials: definitionCredentials.chain({
+      payer: 'organization',
+      tryInOrder: [
+        definitionCredentials.subscription({ owner: 'organization' }),
+        definitionCredentials.platform(),
+      ],
+    }),
+    model: 'gpt-5.5',
+    reasoning: 'low',
+  }),
+});

package/fixtures/assistant-with-tools/agent/instructions.md

@@ -0,0 +1 @@
+Help the user with their requests.

package/fixtures/assistant-with-tools/agent/tools/current_time.ts

@@ -0,0 +1,9 @@
+import { defineTool } from '@finalai/agents';
+import * as z from 'zod';
+
+export default defineTool({
+  description: 'Read the current UTC time from the execution environment.',
+  inputSchema: z.strictObject({}),
+  outputSchema: z.object({ utc: z.string() }),
+  execute: () => ({ utc: new Date().toISOString() }),
+});

package/fixtures/final-connection/agent/agent.ts

@@ -0,0 +1,15 @@
+import { defineAgent, credentials as definitionCredentials } from '@finalai/agents';
+import { serverlessFinal } from '@finalai/final-agent-provider/harnesses';
+
+export default defineAgent({
+  description: 'Works with Goals and conversations through Final.',
+  harness: serverlessFinal({
+    credentials: definitionCredentials.chain({
+      payer: 'organization',
+      tryInOrder: [
+        definitionCredentials.subscription({ owner: 'organization' }),
+        definitionCredentials.platform(),
+      ],
+    }),
+  }),
+});

package/fixtures/final-connection/agent/connections/final.ts

@@ -0,0 +1,9 @@
+import { defineFinalConnection } from '@finalai/agents';
+import { always } from '@finalai/agents/approval';
+
+// Final's MCP server: the session service resolves `final-session` auth to a
+// grant scoped to the calling session.
+export default defineFinalConnection({
+  url: 'https://console.final.test/api/mcp/tools',
+  tools: { approval: { cancel_goal: always() } },
+});

package/fixtures/release-scout/agent/agent.ts

@@ -0,0 +1,22 @@
+import { baseTools, credentials, defineAgent } from '@finalai/agents';
+import { serverlessPi } from '@finalai/agents/harnesses';
+import { computer } from './sandbox';
+
+export default defineAgent({
+  name: 'Release Scout',
+  description: 'Answers release questions, runs checks, posts the daily digest.',
+  // Read by tools/lookup_release_notes.ts and channels/github.ts; linear-token
+  // comes from connections/linear.ts.
+  secrets: ['github-token', 'github-webhook-secret'],
+  // Off unless declared; each capability is bound to a named sandbox target.
+  tools: baseTools({ shell: computer, files: computer }),
+  harness: serverlessPi({
+    model: 'gpt-6-sol',
+    reasoning: 'medium',
+    credentials: credentials.chain({
+      payer: 'organization',
+      tryInOrder: [credentials.apiKey({ owner: 'organization' }), credentials.platform()],
+    }),
+    permissionMode: 'ask',
+  }),
+});

package/fixtures/release-scout/agent/channels/github-signature.ts

@@ -0,0 +1,27 @@
+// A helper next to the channel (no default export, so not a channel itself).
+export const verifyGithubSignature = async (
+  request: Request,
+  body: string,
+  secret: string | null,
+): Promise<boolean> => {
+  const signature = request.headers.get('x-hub-signature-256');
+  if (
+    secret == null ||
+    secret.length === 0 ||
+    signature == null ||
+    !/^sha256=[a-f0-9]{64}$/i.test(signature)
+  )
+    return false;
+  const digest = Uint8Array.from(signature.slice(7).match(/.{2}/g) ?? [], (byte) =>
+    Number.parseInt(byte, 16),
+  );
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['verify'],
+  );
+  return crypto.subtle.verify('HMAC', key, digest, encoder.encode(body));
+};

package/fixtures/release-scout/agent/channels/github.ts

@@ -0,0 +1,38 @@
+import { defineChannel, POST } from '@finalai/agents/channels';
+import * as z from 'zod';
+import { verifyGithubSignature } from './github-signature';
+
+const actionSchema = z.object({ action: z.string() });
+const releaseEventSchema = actionSchema.extend({ release: z.object({ tag_name: z.string() }) });
+
+export default defineChannel({
+  routes: [
+    POST('/webhook', async ({ request, secrets, receive }) => {
+      const body = await request.text();
+      if (
+        !(await verifyGithubSignature(request, body, await secrets.get('github-webhook-secret')))
+      ) {
+        return new Response(null, { status: 401 });
+      }
+      let raw: unknown;
+      try {
+        raw = JSON.parse(body);
+      } catch {
+        return new Response(null, { status: 400 });
+      }
+      const action = actionSchema.safeParse(raw);
+      if (!action.success) return new Response(null, { status: 400 });
+      if (action.data.action !== 'published') return new Response(null, { status: 204 });
+      const parsed = releaseEventSchema.safeParse(raw);
+      if (!parsed.success) return new Response(null, { status: 400 });
+      await receive({
+        target: { kind: 'bound-conversation' },
+        content: [
+          { type: 'text', text: `GitHub release published: ${parsed.data.release.tag_name}` },
+        ],
+      });
+      return new Response(null, { status: 202 });
+    }),
+  ],
+  turnPolicy: 'steer',
+});

package/fixtures/release-scout/agent/connections/linear.ts

@@ -0,0 +1,9 @@
+import { defineMcpClientConnection } from '@finalai/agents';
+import { always } from '@finalai/agents/approval';
+
+export default defineMcpClientConnection({
+  url: 'https://mcp.linear.app/mcp',
+  // Bearer from the secrets manager; the secret never reaches the harness.
+  auth: { secretKey: 'linear-token', headerName: null },
+  tools: { allow: ['search_issues', 'create_issue'], approval: { create_issue: always() } },
+});